reference-data-mcp-server

Overview

Countries, timezones, periodic table elements, physical constants, units, HTTP status codes, and MIME types — all served from static, in-memory datasets, entirely offline with no API keys or rate limits. Look up, search, and convert across these domains from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Resources

All resource data is also reachable via tools — use ref_geo_lookup, ref_element_lookup, and ref_timezone_lookup when you need flexible query modes or country search.

Capability reference

ref_geo_lookup _tool

• Accepts fuzzy name matching ("Brasil" resolves to "Brazil"); a fuzzy hit adds an enrichment notice naming the canonical result
• Lookup modes: auto (alpha2 → alpha3 → name), name, alpha2, alpha3; numeric ISO codes are not supported
• Returns capital, region/subregion, languages, currencies, calling codes, TLD, flag emoji, and IANA timezone IDs

ref_geo_search _tool

• At least one filter required (no_filters error otherwise): keyword (name, native name, capital, subregion), region, subregion, language (ISO 639-1 code or name), or currency (ISO 4217 code or name)
• Limit 1–100 (default 20); truncated flag and totalMatches count when results are cut off
• Empty result set returns a notice echoing the applied filters

ref_timezone_lookup _tool

• Lookup modes: auto (IANA ID → country code → city name), iana, country; partial city matching ("Tokyo" → "Asia/Tokyo", "NY" → "America/New_York")
• Country-code queries return every timezone observed in that country
• Optional at (ISO 8601) evaluates DST state at a specific moment instead of now; malformed values raise invalid_at
• Returns current/standard UTC offsets, DST status and abbreviations, major cities, and country codes

ref_timezone_convert _tool

• datetime must be a local ISO 8601 string without an offset (regex-enforced, e.g. 2026-05-24T15:30:00); from_tz/to_tz accept full IANA IDs or unambiguous city names
• Rejects out-of-range calendar dates and spring-forward DST gaps as invalid_datetime; unrecognized zones as invalid_timezone
• Returns source and target local datetimes with their respective UTC offsets, plus the UTC equivalent

ref_element_lookup _tool

• Lookup modes: auto (atomic number → symbol → name), name, symbol, number
• Full property set: atomic mass (atomic_mass_estimated flag), electron configuration, group/period/block, category, Pauling electronegativity, density, melting/boiling points in kelvin, phase at STP, radioactivity, natural occurrence, discovery data
• Data sourced from PubChem/IUPAC 2024; synthetic or unstable elements return null for experimentally inaccessible properties

ref_element_search _tool

• At least one filter required (no_filters error otherwise): category (partial match), group (1–18), period (1–7), atomic-number range, or atomic-mass range
• Valid categories: alkali metal, alkaline earth metal, transition metal, post-transition metal, metalloid, reactive nonmetal, noble gas, lanthanide, actinide
• Returns summaries (atomic number, symbol, name, mass, category) plus a totalMatches count and a notice when nothing matches

ref_constant_lookup _tool

• Fuzzy alias matching: "speed of light", "c", "Avogadro's number", "N_A", "Planck", "h", "Boltzmann", "k_B" all resolve against 32 CODATA 2022 constants
• match_strategy discriminates how the query resolved: exact_symbol, exact_name, or fuzzy (closest candidate — verify before reuse)
• Returns value, SI unit expression, absolute/relative uncertainty (exact flag for defined constants), CODATA identifier, and up to 3 related constants

ref_unit_convert _tool

• 11 measurement domains: length, mass, volume, temperature (non-linear C/F/K/R), speed, pressure, energy, power, frequency, digital storage, angle
• Mass mt is the metric tonne (1000 kg); t is the US short ton (907.18 kg) — distinct units, easily confused
• Typed errors: incompatible_units (mismatched quantities), unknown_unit (unrecognized abbreviation), below_absolute_zero (with the Kelvin equivalent)

ref_http_status _tool

• Numeric queries (e.g., "404") return an exact match; keyword queries (e.g., "not found", "too many requests") return the closest match plus alternatives
• Returns reason phrase, description, category (1xx–5xx), cacheability per RFC 9110, and the defining RFC with section reference

ref_mime_type _tool

• Accepts "image/webp", ".webp", or "webp" interchangeably
• Extension lookups return the canonical MIME type first; additional types sharing the extension are listed as alternatives
• Returns extensions, a compressibility flag (relevant for Content-Encoding decisions), and the data source (iana/apache/nginx)

ref://countries/{alpha2} _resource

• Full country record as application/json — same fields as ref_geo_lookup
• alpha2 accepts either case; an unmatched code returns a notFound error

ref://elements/{number} _resource

• Full element record as application/json — same fields as ref_element_lookup
• number must be an integer string 1–118; out-of-range or unmatched values return notFound

ref://timezones/{iana_id} _resource

• Timezone record as application/json — same fields as ref_timezone_lookup, plus evaluated_at
• Slashes in the IANA ID must be percent-encoded as %2F (e.g. America%2FNew_York); an unencoded slash matches a separate catch-all that returns an actionable error with the correctly encoded URI

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

Reference-data-specific:

• Entirely in-memory — all datasets load at startup; no runtime network calls, no API keys, no rate limits
• Works offline and in air-gapped environments
• Seven specialized services: geo (countries-list), timezone (Node.js Intl + @vvo/tzdb), elements (PubChem/IUPAC 2024, 118 elements), constants (CODATA 2022, 32 entries), units (convert-units), HTTP status (IANA registry), MIME types (mime-db, ~1,000 types)

Agent-friendly output:

• Structured error contracts on every tool — typed reason codes (no_match, no_filters, unknown_unit, incompatible_units, below_absolute_zero, invalid_timezone, invalid_datetime, invalid_at) with actionable recovery hints
• Discriminated outputs where relevant — truncated flag on search results, alternatives arrays on MIME/HTTP keyword matches, atomic_mass_estimated flag on element data, match_strategy on constant lookups
• Consistent null for genuinely unknown or inapplicable values rather than absent fields

Getting started

Public Hosted Instance

A public instance is available at https://reference-data.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "reference-data-mcp-server": {
      "type": "streamable-http",
      "url": "https://reference-data.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file:

{
  "mcpServers": {
    "reference-data-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/reference-data-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "reference-data-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/reference-data-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "reference-data-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/reference-data-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).
• No API keys required — this server is entirely self-contained.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/reference-data-mcp-server.git

2. Navigate into the directory:

cd reference-data-mcp-server

3. Install dependencies:

bun install

4. Configure environment (optional):

cp .env.example .env
# edit .env if you want to override transport or logging defaults

Configuration

No API keys are required. All configuration is optional overrides of framework defaults.

See .env.example for the full list of optional overrides.

Running the server

Local development

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

bun run devcheck   # Lint, format, typecheck, security
bun run test       # Vitest test suite
bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t reference-data-mcp-server .
docker run --rm -p 3010:3010 reference-data-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/reference-data-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools and resources directly in src/index.ts
• Data integrity: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.