@cyanheads/reference-data-mcp-server

v0.1.6 pre-1.0

Look up countries, timezones, periodic table elements, physical constants, units, HTTP status codes, and MIME types via MCP. STDIO or Streamable HTTP.

@cyanheads/reference-data-mcp-server
claude mcp add --transport http reference-data-mcp-server https://reference-data.caseyjhand.com/mcp
codex mcp add reference-data-mcp-server --url https://reference-data.caseyjhand.com/mcp
{
  "mcpServers": {
    "reference-data-mcp-server": {
      "url": "https://reference-data.caseyjhand.com/mcp"
    }
  }
}
gemini mcp add --transport http reference-data-mcp-server https://reference-data.caseyjhand.com/mcp
{
  "mcpServers": {
    "reference-data-mcp-server": {
      "command": "bunx",
      "args": [
        "@cyanheads/reference-data-mcp-server@latest"
      ]
    }
  }
}
{
  "mcpServers": {
    "reference-data-mcp-server": {
      "type": "http",
      "url": "https://reference-data.caseyjhand.com/mcp"
    }
  }
}
curl -X POST https://reference-data.caseyjhand.com/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'

Tools

10

ref_geo_lookup

Look up a country by name, ISO alpha-2 code (2 letters), or ISO alpha-3 code (3 letters). Returns the full record: capital, region, official languages, currencies, calling codes, TLD, flag emoji, and IANA timezone IDs. Accepts fuzzy name matching — "Brasil" and "Brazil" both resolve.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ref_geo_lookup",
    "arguments": {
      "query": "<query>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Country name (e.g., \"Germany\"), ISO alpha-2 code (e.g., \"DE\"), or ISO alpha-3 code (e.g., \"DEU\")."
    },
    "by": {
      "default": "auto",
      "description": "Lookup strategy: auto tries alpha2, alpha3, then name in order.",
      "type": "string",
      "enum": [
        "auto",
        "name",
        "alpha2",
        "alpha3"
      ]
    }
  },
  "required": [
    "query",
    "by"
  ],
  "additionalProperties": false
}
view source ↗

ref_timezone_lookup

Get timezone info by IANA ID, country code, or partial city/region name. Returns current UTC offset, standard offset, whether DST is currently active, and major cities in the timezone. When querying by country code (ISO alpha-2), returns all timezones observed in that country. Accepts partial matches — "Tokyo" resolves to "Asia/Tokyo", "NY" resolves to "America/New_York".

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ref_timezone_lookup",
    "arguments": {
      "query": "<query>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "IANA timezone ID (e.g., \"America/New_York\"), ISO alpha-2 country code (e.g., \"US\"), or partial city/region name (e.g., \"Tokyo\", \"London\")."
    },
    "by": {
      "default": "auto",
      "description": "Lookup mode: iana for exact IANA ID, country for ISO alpha-2 code, auto tries all strategies.",
      "type": "string",
      "enum": [
        "iana",
        "country",
        "auto"
      ]
    },
    "at": {
      "description": "ISO 8601 datetime to evaluate timezone state at a specific moment (e.g., \"2026-01-15T12:00:00\"). Defaults to current time.",
      "type": "string"
    }
  },
  "required": [
    "query",
    "by"
  ],
  "additionalProperties": false
}
view source ↗

ref_timezone_convert

Convert a local datetime from one timezone to another. Takes a local time string (no UTC offset, e.g., "2026-05-24T15:30:00") interpreted as local time in the source timezone, returns the equivalent local time in the target timezone. Shows both UTC offsets so DST transitions are visible. Accepts full IANA IDs (e.g., "Asia/Tokyo") or unambiguous city names (e.g., "Tokyo").

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ref_timezone_convert",
    "arguments": {
      "datetime": "<datetime>",
      "from_tz": "<from_tz>",
      "to_tz": "<to_tz>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "datetime": {
      "type": "string",
      "description": "Local datetime in ISO 8601 format without timezone offset (e.g., \"2026-05-24T15:30:00\"). Do not include \"Z\" or an offset suffix."
    },
    "from_tz": {
      "type": "string",
      "description": "Source IANA timezone ID or unambiguous city name (e.g., \"Asia/Tokyo\" or \"Tokyo\")."
    },
    "to_tz": {
      "type": "string",
      "description": "Target IANA timezone ID or unambiguous city name (e.g., \"America/New_York\" or \"New York\")."
    }
  },
  "required": [
    "datetime",
    "from_tz",
    "to_tz"
  ],
  "additionalProperties": false
}
view source ↗

ref_element_lookup

Look up a periodic table element by name, chemical symbol, or atomic number. Returns the full data record: atomic number, symbol, name, atomic mass (in unified atomic mass units), electron configuration, group, period, block, category (e.g., "noble gas", "transition metal"), Pauling electronegativity, density (g/cm³), melting and boiling points in kelvin, and discovery year. Properties unavailable for synthetic or insufficiently studied elements are returned as null.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ref_element_lookup",
    "arguments": {
      "query": "<query>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Element name (e.g., \"tungsten\"), chemical symbol (e.g., \"W\"), or atomic number as a string (e.g., \"74\")."
    },
    "by": {
      "default": "auto",
      "description": "Lookup mode: auto tries atomic number, then symbol, then name.",
      "type": "string",
      "enum": [
        "auto",
        "name",
        "symbol",
        "number"
      ]
    }
  },
  "required": [
    "query",
    "by"
  ],
  "additionalProperties": false
}
view source ↗

ref_constant_lookup

Look up a fundamental physical constant by name, symbol, or common alias. Returns the CODATA 2022 value, SI unit expression, relative standard uncertainty, and a short description. Recognizes common names and symbols — "speed of light", "c", "Avogadro's number", "N_A", "Planck", "h", "Boltzmann", "k_B" all resolve correctly. Fuzzy matching returns the closest match plus alternatives.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ref_constant_lookup",
    "arguments": {
      "query": "<query>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Constant name, symbol, or common alias (e.g., \"speed of light\", \"c\", \"Avogadro\", \"N_A\", \"Planck constant\", \"h\")."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}
view source ↗

ref_unit_convert

Convert a numeric value between compatible units of measure. Supports: length (mm, cm, m, km, in, ft, yd, mi), mass (mcg, mg, g, kg, oz, lb, mt, t), volume (ml, cl, dl, l, kl, tsp, Tbs, fl-oz, cup, pnt, qt, gal, m3), temperature (C, F, K, R — non-linear conversions handled), speed (m/s, km/h, knot, ft/s), pressure (Pa, kPa, MPa, hPa, bar, torr, psi), energy (J, kJ, Wh, kWh, MWh), power (W, mW, kW, MW, GW), frequency (Hz, kHz, MHz, GHz), digital storage (b, Kb, Mb, Gb, Tb, B, KB, MB, GB, TB), and angle (deg, rad, grad). Incompatible units (e.g., km to kg) return an error identifying the quantity mismatch.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ref_unit_convert",
    "arguments": {
      "value": "<value>",
      "from": "<from>",
      "to": "<to>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "value": {
      "type": "number",
      "description": "Numeric quantity to convert."
    },
    "from": {
      "type": "string",
      "description": "Source unit abbreviation (e.g., \"km\", \"C\", \"mph\", \"kWh\", \"kg\")."
    },
    "to": {
      "type": "string",
      "description": "Target unit abbreviation (e.g., \"mi\", \"F\", \"m/s\", \"BTU\", \"lb\")."
    }
  },
  "required": [
    "value",
    "from",
    "to"
  ],
  "additionalProperties": false
}
view source ↗

ref_http_status

Look up an HTTP status code by number or keyword. Returns the reason phrase, description, category (1xx Informational, 2xx Success, 3xx Redirection, 4xx Client Error, 5xx Server Error), whether the code is cacheable by default, and the defining RFC with section reference. For keyword queries, returns the closest match plus alternatives.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ref_http_status",
    "arguments": {
      "query": "<query>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Numeric status code (e.g., \"404\" or \"422\") or descriptive keyword (e.g., \"not found\", \"too many requests\", \"unprocessable\")."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}
view source ↗

ref_mime_type

Look up a MIME type by type string or file extension. Accepts "image/webp", ".webp", or "webp". Returns the canonical MIME type, known file extensions, whether the type is compressible (relevant for Content-Encoding decisions), and the data source (iana, apache, nginx). For extension lookups, returns the canonical MIME type — e.g., ".jpg" resolves to "image/jpeg". When multiple types map to an extension, the canonical type is returned first with alternatives listed.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ref_mime_type",
    "arguments": {
      "query": "<query>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "MIME type string (e.g., \"application/json\", \"image/webp\") or file extension with or without leading dot (e.g., \".webp\", \"webp\", \"js\", \".html\")."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}
view source ↗

Resources

4

Full country record by ISO alpha-2 code (e.g., ref://countries/DE for Germany). Returns all fields including capital, region, languages, currencies, calling codes, TLD, flag, and timezone IDs.

uri ref://countries/{alpha2} mime application/json

Full periodic table element record by atomic number (e.g., ref://elements/6 for Carbon). Returns all properties: symbol, name, atomic mass, electron configuration, group, period, block, category, electronegativity, density, melting/boiling points, and discovery data.

uri ref://elements/{number} mime application/json

Timezone info by IANA ID (URL-encode slashes as %2F, e.g., ref://timezones/America%2FNew_York). Returns current offset, standard offset, DST status, major cities, and country codes.

uri ref://timezones/{iana_id} mime application/json

Returns an actionable error when an IANA timezone ID is passed with an unencoded slash (e.g., America/New_York). Instructs the caller to use the correctly percent-encoded URI (America%2FNew_York) and retry.

uri ref://timezones/{region}/{city} mime application/json