io.github.cyanheads/oecd-mcp-server

---

Overview

OECD statistical data via the SDMX 2.1 REST API — 1,500+ dataflows spanning national accounts, employment, trade, education, and health. Search datasets, inspect their dimensions, resolve codes, and query observations, with large multi-country time-series spilling to a queryable DataCanvas table for SQL analysis. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Five discovery and data tools plus two SQL analytics tools for large query results:

Tool	Description
oecd_list_agencies	List OECD SDMX agencies with their directorate and the number of dataflows each publishes
oecd_search_datasets	Search 1,500+ OECD dataflows by keyword or theme
oecd_get_dataset_info	Fetch a dataflow's dimensions, key order, and codelist references
oecd_get_dimension_values	Fetch valid codes and labels for one dimension (countries, measures, frequencies)
oecd_query_dataset	Fetch observations filtered by dimension key and time range; spills large results to DataCanvas
oecd_dataframe_describe	List DataCanvas tables and columns staged by a prior oecd_query_dataset spill
oecd_dataframe_query	Run a read-only SQL SELECT against DataCanvas tables

Resources

Resource	Description
oecd://dataflow/{agency_id}/{flow_id}	Dimension metadata for a single OECD dataflow — same content as oecd_get_dataset_info

All resource data is also reachable via tools. Use oecd_get_dataset_info for the same content.

Capability reference

oecd_list_agencies _tool

• Returns agency IDs (e.g. OECD.SDD.NAD, OECD.ELS.SPD, OECD.EDU.IMEP) and dataflow counts, sorted descending by count
• Each agency carries the name of its directorate — OECD.CTP.TPS is the Centre for Tax Policy and Administration, OECD.SDD.NAD the Statistics and Data Directorate — so a department can be picked without decoding the identifier
• Publishers outside OECD that ship dataflows through the same catalog (ESTAT, IAEG-SDGs) carry no directorate
• Useful for scoping oecd_search_datasets by department (national accounts, labour, education, etc.)

---

oecd_search_datasets _tool

• Token-matching across dataflow names and descriptions — reaches datasets whose name never carries the term, so inflation returns Economic Outlook 119 and poverty returns Income inequality - Regions
• Each result reports matched_in (name, description, or both) and a plain-text description trimmed to 240 characters
• Optional agency_id filter scopes results to a specific statistical department
• limit (1–100) and offset page through the match list; total_matches reports the full count
• Returns flow_ref values (e.g. OECD.SDD.NAD,DSD_NAAG@DF_NAAG_I) — pass directly to oecd_get_dataset_info or oecd_query_dataset. A handful of dataflows are catalogued without a datastructure prefix and come back in the bare {agencyID},{df_id} form (OECD.TAD.ARP,DF_AEI2024_DASHBOARD); both forms are accepted everywhere a flow_ref is
• Fetches and filters in-memory; the full catalog is ~5.9 MB and bounded (OECD adds datasets weekly, not continuously)

---

oecd_get_dataset_info _tool

• Returns all dimensions in key order (position 1, 2, 3 …) — dimension order is required to construct the dot-delimited key for oecd_query_dataset
• Each dimension carries its concept name from the datastructure's concept scheme, so INSTR_ASSET reads as "Financial instruments and non-financial assets" rather than repeating the id. A dimension the scheme does not cover keeps the id
• Shows codelist references for each dimension — pass to oecd_get_dimension_values to resolve human-readable names to SDMX codes
• Surfaces NonProductionDataflow flag — marks experimental or deprecated dataflows
• Resolves a flow_ref whose id prefix names no datastructure of its own by asking the dataflow for its structure — OECD.CFE.EDS,DSD_REG_LAB@DF_RATES is backed by DSD_REG_LABOUR, and answers here rather than reporting the dataflow as missing
• Required before calling oecd_query_dataset on an unfamiliar dataflow

---

oecd_get_dimension_values _tool

• Returns code + label pairs for a single dimension (e.g. REF_AREA → USA/United States, DEU/Germany)
• query matches a case-insensitive substring against both the code and its label, so PA and percent each reach PA / Percent per annum
• limit (1–500, default 50) and offset page the matching list. Both client surfaces carry the same page, so a 1,164-code dimension like UNIT_MEASURE no longer ships 66 KB of pairs to structuredContent to find one code
• When matches remain beyond the page, the response reports the full match count and how to reach the rest

---

oecd_query_dataset _tool

• Dot-delimited key (e.g. A.USA+DEU.B1GQ_R.PC.) with +-separated multi-values and empty wildcard segments; optional start_period / end_period bound the range (ISO format: 2010, 2010-Q1)
• SDMX-JSON decoded into row objects — every dimension and observation attribute (UNIT_MULT, OBS_STATUS, PRICE_BASE, DECIMALS, …) becomes its own column, so an estimated or break-flagged point is distinguishable from a confirmed one
• value is pre-multiplied by value_scale (the observation's unit multiplier) — a GDP figure OECD publishes as 26054.614 billions comes back as 26054614000000; divide by value_scale for the figure as OECD published it. Every row carries source: "OECD"
• Small results return every observation inline with no canvas_id; large results (multi-country, multi-year) spill to DataCanvas (CANVAS_PROVIDER_TYPE=duckdb) with truncated: true plus a canvas_id / table_name for oecd_dataframe_describe and oecd_dataframe_query; without DataCanvas every row still returns in structuredContent, but the rendered table caps at a preview slice, reported via content_table_capped

---

oecd_dataframe_describe _tool

• Lists table and view names, row counts, and column names/types staged on a DataCanvas by a prior oecd_query_dataset spill
• Takes the canvas_id oecd_query_dataset returned
• Only available when CANVAS_PROVIDER_TYPE=duckdb is set — call before oecd_dataframe_query to discover exact table and column names for SQL

---

oecd_dataframe_query _tool

• Runs a single read-only SQL SELECT against the staged tables — aggregates, window functions, GROUP BY, ORDER BY, and standard DuckDB SQL
• Writes, DDL, and system-catalog access are rejected
• Results capped at the canvas row limit; row_count reports the full count before the cap
• Only available when CANVAS_PROVIDER_TYPE=duckdb is set

---

oecd://dataflow/{agency_id}/{flow_id} _resource

• Dimension metadata for a single OECD dataflow as application/json — same content as oecd_get_dataset_info
• {flow_id} is the combined {dsd_id}@{df_id} string with @ percent-encoded as %40, or the bare {df_id} for a dataflow catalogued without a datastructure prefix
• Example: oecd://dataflow/OECD.SDD.NAD/DSD_NAAG%40DF_NAAG_I

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.

OECD-specific:

• Keyless access — no API key required; OECD SDMX 2.1 REST API is fully public
• Covers 1,500+ dataflows across 20+ OECD statistical departments (national accounts, employment, inflation, trade, education, health, environment, taxation, inequality)
• Delegated dataflows and codelist revisions resolved end to end — a dataflow OECD catalogues on one service root but defines on another follows the catalog's own link for structure, codes, and observations, and codes come from the revision the datastructure names rather than the endpoint's current latest
• AllDimensions observation mode — one-pass SDMX-JSON decoding into flat row objects, no nested series key reconstruction
• oecd_query_dataset materializes large observation sets (multi-country time-series) on a DuckDB DataCanvas for in-conversation SQL analytics

Agent-friendly output:

• Workflow-aware tool surface — flow_ref from search flows directly into info, values, and query tools without reconstruction
• Spill signaling — truncated: true + canvas_id tells the agent to switch to SQL instead of parsing a truncated inline list
• Full SDMX decoding server-side — agents see { REF_AREA: "United States", MEASURE: "Gross domestic product", UNIT_MULT: "Billions", value: 26054614000000, value_scale: 1000000000 }, not raw index arrays

Getting started

Public Hosted Instance

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

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

Self-Hosted / Local

Add the following to your MCP client configuration file.

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

Or with npx (no Bun required):

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

Or with Docker:

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

To enable DataCanvas SQL analytics for large query results, add CANVAS_PROVIDER_TYPE=duckdb:

{
  "mcpServers": {
    "oecd-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/oecd-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "CANVAS_PROVIDER_TYPE": "duckdb"
      }
    }
  }
}

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 key required — OECD SDMX is a free, public API.

Installation

1. Clone the repository:

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

2. Navigate into the directory:

cd oecd-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# edit .env — most vars are optional; no API key required

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:

Variable	Description	Default
OECD_BASE_URL	OECD SDMX REST API base URL. Must be an https origin that answers directly — no redirect is followed, so a plaintext http:// origin fails instead of being upgraded to https.	https://sdmx.oecd.org/public/rest
OECD_TIMEOUT_MS	Per-request timeout in milliseconds.	30000
CANVAS_PROVIDER_TYPE	Canvas engine. Set to duckdb so a large oecd_query_dataset result spills to a queryable table instead of just capping the rendered preview — unset, every row still comes back in structuredContent, only the rendered table is capped.	none
MCP_TRANSPORT_TYPE	Transport: stdio or http.	stdio
MCP_HTTP_PORT	Port for HTTP server.	3010
MCP_SESSION_MODE	HTTP session posture: stateful, stateless, or auto. The server declares stateless in source — it keeps no per-session state, and a DataCanvas handle is keyed by canvas_id — so set this only to override that.	stateless
MCP_AUTH_MODE	Auth mode: none, jwt, or oauth.	none
MCP_LOG_LEVEL	Log level (RFC 5424).	info
LOGS_DIR	Directory for log files (Node.js only).	<project-root>/logs
OTEL_ENABLED	Enable OpenTelemetry instrumentation.	false

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

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• Run checks and tests:

  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 oecd-mcp-server .
docker run --rm -p 3010:3010 oecd-mcp-server

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

Project structure

Directory	Purpose
src/index.ts	createApp() entry point — registers tools/resources and initializes services.
src/config/	Server-specific environment variable parsing and validation with Zod.
src/mcp-server/tools/definitions/	Tool definitions (*.tool.ts) — seven tools for OECD data discovery and retrieval.
src/mcp-server/resources/definitions/	Resource definitions (*.resource.ts) — the oecd://dataflow resource.
src/services/oecd-http/	Shared OECD fetch boundary — timeout and retry-classification corrections used by both services below, the origin check every delegated service root passes before it is addressed, the refusal of any redirect off the configured host, and the classification that gives an upstream refusal the same declared reason on every tool and resource.
src/services/oecd-structure/	OECD SDMX structure service — dataflows, data structures, codelists.
src/services/oecd-data/	OECD SDMX data service — observations, SDMX-JSON decoding, DataCanvas spillover.
src/services/canvas-accessor/	DataCanvas accessor — registers and exposes the framework canvas instance to tools.
tests/	Unit and integration tests mirroring src/.

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 via the barrels in src/mcp-server/*/index.ts
• Wrap external API calls: validate raw SDMX-JSON → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome — see CONTRIBUTING.md for what makes one actionable, and CODE_OF_CONDUCT.md for how we work together. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.