{"id":50993853,"url":"https://github.com/cyanheads/oecd-mcp-server","last_synced_at":"2026-06-20T06:32:37.032Z","repository":{"id":363050769,"uuid":"1259945508","full_name":"cyanheads/oecd-mcp-server","owner":"cyanheads","description":"Search, explore, and query 1,500+ OECD statistical datasets (national accounts, employment, trade, PISA, health) via SDMX via MCP. STDIO or Streamable HTTP. ","archived":false,"fork":false,"pushed_at":"2026-06-07T06:40:47.000Z","size":552,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-07T08:15:01.007Z","etag":null,"topics":["ai-agents","ai-tools","cyanheads","economics","mcp","mcp-server","model-context-protocol","oecd","sdmx","statistics","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@cyanheads/oecd-mcp-server","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cyanheads.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-05T02:35:19.000Z","updated_at":"2026-06-07T06:40:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cyanheads/oecd-mcp-server","commit_stats":null,"previous_names":["cyanheads/oecd-mcp-server"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/cyanheads/oecd-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyanheads%2Foecd-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyanheads%2Foecd-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyanheads%2Foecd-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyanheads%2Foecd-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cyanheads","download_url":"https://codeload.github.com/cyanheads/oecd-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyanheads%2Foecd-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34560265,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-tools","cyanheads","economics","mcp","mcp-server","model-context-protocol","oecd","sdmx","statistics","typescript"],"created_at":"2026-06-20T06:32:36.263Z","updated_at":"2026-06-20T06:32:37.008Z","avatar_url":"https://github.com/cyanheads.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003e@cyanheads/oecd-mcp-server\u003c/h1\u003e\n  \u003cp\u003e\u003cb\u003eSearch, explore, and query 1,500+ OECD statistical datasets (national accounts, employment, trade, PISA, health) via SDMX via MCP. STDIO or Streamable HTTP.\u003c/b\u003e\n  \u003cdiv\u003e7 Tools • 1 Resource\u003c/div\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![Version](https://img.shields.io/badge/Version-0.1.3-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square\u0026logo=docker\u0026logoColor=white)](https://github.com/users/cyanheads/packages/container/package/oecd-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/oecd-mcp-server?style=flat-square\u0026logo=npm\u0026logoColor=white)](https://www.npmjs.com/package/@cyanheads/oecd-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.11-blueviolet.svg?style=flat-square)](https://bun.sh/)\n\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge\u0026logo=anthropic\u0026logoColor=white)](https://github.com/cyanheads/oecd-mcp-server/releases/latest/download/oecd-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=oecd-mcp-server\u0026config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvb2VjZC1tY3Atc2VydmVyIl19) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge\u0026logo=visualstudiocode\u0026logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22oecd-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Foecd-mcp-server%22%5D%7D)\n\n[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)\n\n\u003c/div\u003e\n\n---\n\n## Tools\n\nFive discovery and data tools plus two SQL analytics tools for large query results:\n\n| Tool | Description |\n|:-----|:------------|\n| `oecd_list_agencies` | List OECD SDMX agencies and the number of dataflows each publishes |\n| `oecd_search_datasets` | Search 1,500+ OECD dataflows by keyword or theme |\n| `oecd_get_dataset_info` | Fetch a dataflow's dimensions, key order, and codelist references |\n| `oecd_get_dimension_values` | Fetch valid codes and labels for one dimension (countries, measures, frequencies) |\n| `oecd_query_dataset` | Fetch observations filtered by dimension key and time range; spills large results to DataCanvas |\n| `oecd_dataframe_describe` | List DataCanvas tables and columns staged by a prior `oecd_query_dataset` spill |\n| `oecd_dataframe_query` | Run a read-only SQL SELECT against DataCanvas tables |\n\n### `oecd_list_agencies`\n\nEntry point for discovery — enumerate OECD's statistical departments before searching.\n\n- Returns agency IDs (e.g. `OECD.SDD.NAD`, `OECD.ELS`, `OECD.EDU`) and dataflow counts\n- Useful for scoping `oecd_search_datasets` by department (national accounts, labour, education, etc.)\n\n---\n\n### `oecd_search_datasets`\n\nSearch the full catalog of 1,500+ OECD dataflows by keyword or department.\n\n- Token-matching across dataflow names — finds GDP, PISA, trade, inflation, and other datasets by description\n- Optional `agency_id` filter scopes results to a specific statistical department\n- 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`\n- Fetches and filters in-memory; the full catalog is ~800 KB and bounded (OECD adds datasets weekly, not continuously)\n\n---\n\n### `oecd_get_dataset_info`\n\nInspect a dataflow's structure before querying.\n\n- Returns all dimensions in key order (position 1, 2, 3 …) — dimension order is required to construct the dot-delimited key for `oecd_query_dataset`\n- Shows codelist references for each dimension — pass to `oecd_get_dimension_values` to resolve human-readable names to SDMX codes\n- Surfaces `NonProductionDataflow` flag — marks experimental or deprecated dataflows\n- Required before calling `oecd_query_dataset` on an unfamiliar dataflow\n\n---\n\n### `oecd_get_dimension_values`\n\nResolve human-readable names (countries, measures) to SDMX codes.\n\n- Returns all valid code + label pairs for a single dimension (e.g. `REF_AREA` → `USA`/`United States`, `DEU`/`Germany`)\n- The `REF_AREA` codelist has 570+ entries and is returned in full\n- Use substring matching on the returned list to find the right code before building a key\n\n---\n\n### `oecd_query_dataset`\n\nFetch observations from an OECD dataflow filtered by dimension key and time range.\n\n- Accepts a dot-delimited key (e.g. `A.USA+DEU.B1GQ_R.PC.`) where empty segments are wildcards and `+` separates multiple values\n- Optional `start_period` / `end_period` bound the time range (ISO format: `2010`, `2010-Q1`)\n- Decodes SDMX-JSON index notation (`0:0:2:3:0`) into human-readable row objects with dimension labels\n- Every response row includes `source: \"OECD\"` per OECD terms of use\n- **Small results** (few countries, narrow time range): all observations returned inline\n- **Large results** (multi-country, multi-year time-series): returns a `canvas_id` + `truncated: true` — use `oecd_dataframe_describe` to list tables, then `oecd_dataframe_query` for SQL analytics\n\n---\n\n### `oecd_dataframe_describe` / `oecd_dataframe_query`\n\nSQL analytics over observation data staged by `oecd_query_dataset`.\n\nWhen `oecd_query_dataset` returns `truncated: true`, the full result is staged on a DuckDB-backed DataCanvas. Pass the `canvas_id` to:\n\n- **`oecd_dataframe_describe`** — list staged table names and their columns. Run this first to discover the schema before writing SQL.\n- **`oecd_dataframe_query`** — run a single-statement SQL SELECT. Supports aggregates, window functions, GROUP BY, ORDER BY, and standard DuckDB SQL.\n\nRequires `CANVAS_PROVIDER_TYPE=duckdb`. Read-only: writes, DDL, and system catalog access are rejected.\n\n**Typical workflow for a large query:**\n\n```text\noecd_query_dataset → { canvas_id, truncated: true, rows: [preview...] }\n  → oecd_dataframe_describe(canvas_id) → table/column names\n  → oecd_dataframe_query(canvas_id, \"SELECT ref_area, AVG(obs_value) FROM df_... GROUP BY ref_area\")\n```\n\n## Resources\n\n| Type | Name | Description |\n|:-----|:-----|:------------|\n| Resource | `oecd://dataflow/{agency_id}/{flow_id}` | Dimension metadata for a single OECD dataflow — same content as `oecd_get_dataset_info` |\n\n`{flow_id}` is the combined `{dsd_id}@{df_id}` string with `@` percent-encoded as `%40`. Example: `oecd://dataflow/OECD.SDD.NAD/DSD_NAAG%40DF_NAAG_I`.\n\nAll resource data is also reachable via tools. Use `oecd_get_dataset_info` for the same content.\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):\n\n- Declarative tool, resource, and prompt definitions — single file per primitive, framework handles registration and validation\n- Unified error handling — handlers throw, framework catches, classifies, and formats\n- Pluggable auth: `none`, `jwt`, `oauth`\n- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`\n- Structured logging with optional OpenTelemetry tracing\n- STDIO and Streamable HTTP transports\n\nOECD-specific:\n\n- Keyless access — no API key required; OECD SDMX 2.1 REST API is fully public\n- Covers 1,500+ dataflows across 20+ OECD statistical departments (national accounts, employment, inflation, trade, education, health, environment, taxation, inequality)\n- `AllDimensions` observation mode — one-pass SDMX-JSON decoding into flat row objects; no nested series key reconstruction\n- `oecd_query_dataset` materializes large observation sets (multi-country time-series) on a DuckDB DataCanvas for in-conversation SQL analytics\n- OECD source attribution (`source: \"OECD\"`) on every observation row per OECD terms of use\n\nAgent-friendly output:\n\n- Workflow-aware tool surface — `flow_ref` from search flows directly into info, values, and query tools without reconstruction\n- Spill signaling — `truncated: true` + `canvas_id` tells the agent to switch to SQL instead of parsing a truncated inline list\n- Full SDMX decoding server-side — agents see `{ ref_area: \"United States\", measure: \"Gross domestic product\", obs_value: 26054 }`, not raw index arrays\n\n## Getting started\n\nAdd the following to your MCP client configuration file.\n\n```json\n{\n  \"mcpServers\": {\n    \"oecd-mcp-server\": {\n      \"type\": \"stdio\",\n      \"command\": \"bunx\",\n      \"args\": [\"@cyanheads/oecd-mcp-server@latest\"],\n      \"env\": {\n        \"MCP_TRANSPORT_TYPE\": \"stdio\",\n        \"MCP_LOG_LEVEL\": \"info\"\n      }\n    }\n  }\n}\n```\n\nOr with npx (no Bun required):\n\n```json\n{\n  \"mcpServers\": {\n    \"oecd-mcp-server\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@cyanheads/oecd-mcp-server@latest\"],\n      \"env\": {\n        \"MCP_TRANSPORT_TYPE\": \"stdio\",\n        \"MCP_LOG_LEVEL\": \"info\"\n      }\n    }\n  }\n}\n```\n\nOr with Docker:\n\n```json\n{\n  \"mcpServers\": {\n    \"oecd-mcp-server\": {\n      \"type\": \"stdio\",\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"-i\", \"--rm\",\n        \"-e\", \"MCP_TRANSPORT_TYPE=stdio\",\n        \"ghcr.io/cyanheads/oecd-mcp-server:latest\"\n      ]\n    }\n  }\n}\n```\n\nTo enable DataCanvas SQL analytics for large query results, add `CANVAS_PROVIDER_TYPE=duckdb`:\n\n```json\n{\n  \"mcpServers\": {\n    \"oecd-mcp-server\": {\n      \"type\": \"stdio\",\n      \"command\": \"bunx\",\n      \"args\": [\"@cyanheads/oecd-mcp-server@latest\"],\n      \"env\": {\n        \"MCP_TRANSPORT_TYPE\": \"stdio\",\n        \"CANVAS_PROVIDER_TYPE\": \"duckdb\"\n      }\n    }\n  }\n}\n```\n\nFor Streamable HTTP, set the transport and start the server:\n\n```sh\nMCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http\n# Server listens at http://localhost:3010/mcp\n```\n\n### Prerequisites\n\n- [Bun v1.3.11](https://bun.sh/) or higher (or Node.js v24+).\n- No API key required — OECD SDMX is a free, public API.\n\n### Installation\n\n1. **Clone the repository:**\n\n```sh\ngit clone https://github.com/cyanheads/oecd-mcp-server.git\n```\n\n2. **Navigate into the directory:**\n\n```sh\ncd oecd-mcp-server\n```\n\n3. **Install dependencies:**\n\n```sh\nbun install\n```\n\n4. **Configure environment:**\n\n```sh\ncp .env.example .env\n# edit .env — most vars are optional; no API key required\n```\n\n## Configuration\n\nAll configuration is validated at startup via Zod schemas in `src/config/server-config.ts`. Key environment variables:\n\n| Variable | Description | Default |\n|:---------|:------------|:--------|\n| `OECD_BASE_URL` | OECD SDMX REST API base URL. | `https://sdmx.oecd.org/public/rest` |\n| `OECD_TIMEOUT_MS` | Per-request timeout in milliseconds. | `30000` |\n| `CANVAS_PROVIDER_TYPE` | Canvas engine. Set to `duckdb` to enable DataCanvas for large `oecd_query_dataset` results. | `none` |\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |\n| `MCP_HTTP_PORT` | Port for HTTP server. | `3010` |\n| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |\n| `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |\n| `LOGS_DIR` | Directory for log files (Node.js only). | `\u003cproject-root\u003e/logs` |\n| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` |\n\nSee [`.env.example`](./.env.example) for the full list of optional overrides.\n\n## Running the server\n\n### Local development\n\n- **Build and run:**\n\n  ```sh\n  # One-time build\n  bun run rebuild\n\n  # Run the built server\n  bun run start:stdio\n  # or\n  bun run start:http\n  ```\n\n- **Run checks and tests:**\n\n  ```sh\n  bun run devcheck   # Lint, format, typecheck, security\n  bun run test       # Vitest test suite\n  bun run lint:mcp   # Validate MCP definitions against spec\n  ```\n\n### Docker\n\n```sh\ndocker build -t oecd-mcp-server .\ndocker run --rm -p 3010:3010 oecd-mcp-server\n```\n\nThe 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.\n\n## Project structure\n\n| Directory | Purpose |\n|:----------|:--------|\n| `src/index.ts` | `createApp()` entry point — registers tools/resources and initializes services. |\n| `src/config/` | Server-specific environment variable parsing and validation with Zod. |\n| `src/mcp-server/tools/definitions/` | Tool definitions (`*.tool.ts`) — seven tools for OECD data discovery and retrieval. |\n| `src/mcp-server/resources/definitions/` | Resource definitions (`*.resource.ts`) — the `oecd://dataflow` resource. |\n| `src/services/oecd-structure/` | OECD SDMX structure service — dataflows, data structures, codelists. |\n| `src/services/oecd-data/` | OECD SDMX data service — observations, SDMX-JSON decoding, DataCanvas spillover. |\n| `src/services/canvas-accessor/` | DataCanvas accessor — registers and exposes the framework canvas instance to tools. |\n| `tests/` | Unit and integration tests mirroring `src/`. |\n\n## Development guide\n\nSee [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:\n\n- Handlers throw, framework catches — no `try/catch` in tool logic\n- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage\n- Register new tools and resources via the barrels in `src/mcp-server/*/index.ts`\n- Wrap external API calls: validate raw SDMX-JSON → normalize to domain type → return output schema; never fabricate missing fields\n\n## Contributing\n\nIssues and pull requests are welcome. Run checks and tests before submitting:\n\n```sh\nbun run devcheck\nbun run test\n```\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyanheads%2Foecd-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcyanheads%2Foecd-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyanheads%2Foecd-mcp-server/lists"}