Oecd Mcp Server

---

Overview

OECD statistics across 1,500+ datasets on national accounts, employment, trade, education, and health. Search datasets, inspect their dimensions, query observations, and run SQL over large multi-country time series. No API key required.

Tools

Five discovery and data tools plus three DataCanvas 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
oecd_dataframe_drop	Drop a staged DataCanvas table or view once the analysis is done — opt-in via OECD_DATAFRAME_DROP_ENABLED=true

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.

Skill

Skill	Description
oecd-guide	Building SDMX keys, confirming which series a dataflow carries, and reading results without mixing breakdowns, units, or country aggregates. Served over MCP at skill://oecd-guide/SKILL.md

Capability reference

oecd_list_agencies _tool

• No inputs; returns every agency ID (e.g. OECD.SDD.NAD) with its directorate name and dataflow count, sorted by count
• Publishers outside OECD that ship dataflows through the same catalog (ESTAT, IAEG-SDGs) carry no directorate

---

oecd_search_datasets _tool

• query token-matched across dataflow names and descriptions; optional agency_id scope; limit (1–100) and offset paging with total_matches
• Each result carries its flow_ref — the identifier every other tool takes — and matched_in (name, description, or both)

---

oecd_get_dataset_info _tool

• Takes a flow_ref; returns every dimension in key order with its concept name and codelist reference, plus a key_example for oecd_query_dataset
• Fails invalid_flow_ref for a string that is not a flow reference and dataflow_not_found for one OECD does not publish

---

oecd_get_dimension_values _tool

• Takes a flow_ref and dimension_id; optional query substring-matches both code and label
• limit (1–500, default 50) and offset page the matches, with the full match count when more remain

---

oecd_query_dataset _tool

• flow_ref plus a dot-delimited key (+ for multiple values, empty segments as wildcards) and optional start_period / end_period
• One row per observation with every dimension and attribute as its own column; value is pre-multiplied by value_scale
• Large results spill to DataCanvas with truncated: true, canvas_id, and table_name; without a canvas every row stays in structuredContent and only the rendered table is capped (content_table_capped)
• A spill includes a notice naming the canvas and table: inspect columns with oecd_dataframe_describe, then use oecd_dataframe_query for SQL over the full result. Fitting results allocate no new canvas; an explicit canvas_id is checked before the download, so a stale one fails as canvas_not_found without spending an OECD request.

---

oecd_dataframe_describe _tool

• Takes the canvas_id oecd_query_dataset returned; lists each staged table and view with its row count and column names and types

---

oecd_dataframe_query _tool

• canvas_id plus one read-only SQL SELECT; writes, DDL, and system-catalog access are rejected
• limit (default 100) returns up to 1,000 rows per call, within 1 MiB of row data; a limit from 1,001 to 10,000 is served at 1,000 with a notice
• truncated: true marks a result with more rows than it returned, and its notice names how to reach the rest; row_count counts the rows returned
• A query still running after 30 seconds is stopped with query_timeout

---

oecd_dataframe_drop _tool

• canvas_id plus a table_name as oecd_dataframe_describe lists it; returns the dropped object's kind and the remaining_tables
• Opt-in: listed but not callable unless OECD_DATAFRAME_DROP_ENABLED=true

---

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

• Same content as oecd_get_dataset_info, as application/json
• {flow_id} is {dsd_id}@{df_id} with @ encoded as %40 (e.g. oecd://dataflow/OECD.SDD.NAD/DSD_NAAG%40DF_NAAG_I), or the bare {df_id}

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; the oecd_dataframe_* tools work on it; DataCanvas is on by default and CANVAS_PROVIDER_TYPE=none disables it

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

Connect to the hosted instance, no install:

claude mcp add --transport http oecd-mcp-server https://oecd.caseyjhand.com/mcp

Or run it locally:

claude mcp add oecd-mcp-server -- npx -y @cyanheads/oecd-mcp-server

For other clients, add this to the MCP config file:

{
  "mcpServers": {
    "oecd-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/oecd-mcp-server"]
    }
  }
}

No API key is needed — OECD SDMX is a free, public API. DataCanvas SQL analytics over large query results is on by default; set CANVAS_PROVIDER_TYPE=none to get capped inline previews instead. For Docker or a source build, see Running the server.

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. With duckdb, a large oecd_query_dataset result spills to a queryable table instead of just capping the rendered preview; with none, every row still comes back in structuredContent and only the rendered table is capped.	duckdb
OECD_DATAFRAME_DROP_ENABLED	Set to true to register oecd_dataframe_drop. Off, the tool is listed as disabled and clients cannot call it.	false
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
LOG_TOOL_FAILURE_PAYLOADS	Log each failed tool call's arguments and result, redacted by key name and capped at LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES (default 16384). A secret inside a free-form value is not redacted.	false
OTEL_ENABLED	Enable OpenTelemetry instrumentation.	false

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

Running the server

Local development

Requires Bun v1.4.0 or higher (or Node.js v24+).

• Clone and install:

  git clone https://github.com/cyanheads/oecd-mcp-server.git
  cd oecd-mcp-server && bun install
  cp .env.example .env   # optional — every variable has a default
  

• 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 run --rm -p 3010:3010 ghcr.io/cyanheads/oecd-mcp-server:latest

The image defaults to HTTP transport, stateless session mode, and logs to /var/log/oecd-mcp-server. To run it over stdio from an MCP client, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/oecd-mcp-server:latest"]. To build locally, docker build -t 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) — eight tools for OECD data discovery, retrieval, and DataCanvas analysis.
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 response-body reader both share, 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.
skills/	Published agent skill (oecd-guide), served over MCP and shipped in the npm package and Docker image.
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.