Search and fetch ~800K Federal Reserve economic time-series from the FRED API via MCP. STDIO or Streamable HTTP.\n
8 Tools
\n \n
\n\n
\n\n[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/federal-reserve-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/federal-reserve-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)\n\n[](https://github.com/cyanheads/federal-reserve-mcp-server/releases/latest/download/federal-reserve-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=federal-reserve-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvZmVkZXJhbC1yZXNlcnZlLW1jcC1zZXJ2ZXIiXX0=) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22federal-reserve-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads/federal-reserve-mcp-server%22%5D%7D)\n\n[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)\n\n
\n\n---\n\n## Tools\n\nFive FRED tools plus three DataCanvas tools for querying spilled observation results via SQL:\n\n| Tool | Description |\n|:-----|:------------|\n| `fedreserve_search_series` | Full-text search across FRED series titles, units, frequency, and tags — returns matching series IDs with metadata |\n| `fedreserve_get_series` | Fetch metadata for one or more series (title, units, frequency, seasonal adjustment, observation range) |\n| `fedreserve_get_observations` | Fetch date+value observation data for one or more series with date-range filtering and unit transformations |\n| `fedreserve_browse_categories` | Navigate the FRED category tree; drill into a category to see child categories and a series sample |\n| `fedreserve_get_release` | Look up a FRED release by ID or name search — returns release metadata and its associated series list |\n| `fedreserve_dataframe_describe` | List active DataCanvas dataframes registered by this server (canvas IDs, row counts, schemas) |\n| `fedreserve_dataframe_query` | Run a SELECT query against a registered DataCanvas dataframe |\n| `fedreserve_dataframe_drop` | Drop a DataCanvas dataframe by name (opt-in via `FRED_DATAFRAME_DROP_ENABLED=true`) |\n\n### `fedreserve_search_series`\n\nSearch for FRED series by free-text query across titles, tags, and notes.\n\n- Full-text and series-ID search modes\n- Post-search filtering by frequency, units, or seasonal adjustment status\n- Tag-name filtering (semicolon-delimited list)\n- Pagination via `limit` and `offset`\n- To find series for a specific release, use `fedreserve_get_release` instead\n\n---\n\n### `fedreserve_get_series`\n\nFetch metadata for one or more FRED series.\n\n- Accepts up to 50 series IDs in a single call\n- Returns title, units, frequency, seasonal adjustment, observation range, popularity, and notes\n- Fires parallel upstream requests (no FRED batch endpoint exists); partial success reported per ID\n\n---\n\n### `fedreserve_get_observations`\n\nFetch observation data (date + value pairs) for one or more series.\n\n- Accepts up to 10 series IDs; fires one upstream request per series in parallel\n- Date-range filtering with ISO 8601 dates (`observation_start`, `observation_end`)\n- FRED's native unit transformations: `lin`, `chg`, `ch1`, `pch`, `pc1`, `pca`, `cch`, `cca`, `log`\n- Frequency downsampling with configurable aggregation method (`avg`, `sum`, `eop`)\n- Multi-series or >500-row results spill to a DataCanvas table; response includes a `dataset.name` handle for SQL querying via `fedreserve_dataframe_query`\n- Degrades gracefully when DataCanvas is unavailable — returns inline preview with row count\n\n---\n\n### `fedreserve_browse_categories`\n\nNavigate the FRED category hierarchy.\n\n- Omit `category_id` to start at the root (ID 0)\n- Provide a `category_id` to see child categories and a series sample for leaf categories\n- Covers all FRED domains: Money & Banking, National Accounts, Employment, Prices, Housing, Trade, and more\n\n---\n\n### `fedreserve_get_release`\n\nInspect a FRED data release and its associated series.\n\n- Look up by `release_id` (integer) or `release_search` (case-insensitive substring match)\n- Name search fetches all releases and filters client-side (FRED has no server-side release search)\n- Returns release name, link, scheduled dates, and a paginated series list\n- Use `series_limit` and `series_offset` to page through large releases\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):\n\n- Declarative tool definitions — single file per tool, framework handles registration and validation\n- Unified error handling across all tools\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\nFRED-specific:\n\n- Read-only access to the St. Louis Fed's FRED API (`api.stlouisfed.org/fred`)\n- Parallel multi-series fetching via `Promise.allSettled` with partial success reporting\n- DataCanvas spillover for multi-series or large observation results — spilled tables queryable via `fedreserve_dataframe_query`\n- Retry with backoff and 429 rate-limit detection against FRED's 120 req/min limit\n- FRED's native unit transformations delegated server-side for precision against the full series history\n\n## Getting started\n\nAdd the following to your MCP client configuration file. Obtain a free FRED API key at [research.stlouisfed.org/docs/api/api_key.html](https://research.stlouisfed.org/docs/api/api_key.html).\n\n```json\n{\n \"mcpServers\": {\n \"federal-reserve-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"bunx\",\n \"args\": [\"@cyanheads/federal-reserve-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\",\n \"FRED_API_KEY\": \"your-api-key\"\n }\n }\n }\n}\n```\n\nOr with npx (no Bun required):\n\n```json\n{\n \"mcpServers\": {\n \"federal-reserve-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cyanheads/federal-reserve-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\",\n \"FRED_API_KEY\": \"your-api-key\"\n }\n }\n }\n}\n```\n\nOr with Docker:\n\n```json\n{\n \"mcpServers\": {\n \"federal-reserve-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"-i\", \"--rm\",\n \"-e\", \"MCP_TRANSPORT_TYPE=stdio\",\n \"-e\", \"FRED_API_KEY=your-api-key\",\n \"ghcr.io/cyanheads/federal-reserve-mcp-server:latest\"\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 FRED_API_KEY=... bun run start:http\n# Server listens at http://localhost:3010/mcp\n```\n\n### Prerequisites\n\n- [Bun v1.3.2](https://bun.sh/) or higher.\n- A free FRED API key from [stlouisfed.org](https://fredaccount.stlouisfed.org/login/secure/). The key grants 120 requests/minute.\n\n### Installation\n\n1. **Clone the repository:**\n\n```sh\ngit clone https://github.com/cyanheads/federal-reserve-mcp-server.git\n```\n\n2. **Navigate into the directory:**\n\n```sh\ncd federal-reserve-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 and set FRED_API_KEY\n```\n\n## Configuration\n\nAll configuration is validated at startup via Zod schemas in `src/config/server-config.ts`.\n\n| Variable | Description | Default |\n|:---------|:------------|:--------|\n| `FRED_API_KEY` | **Required.** API key from [stlouisfed.org](https://research.stlouisfed.org/docs/api/api_key.html). | — |\n| `FRED_BASE_URL` | Override the FRED API base URL. | `https://api.stlouisfed.org/fred` |\n| `FRED_DATASET_TTL_SECONDS` | Sliding TTL for DataCanvas-registered observation tables (seconds). | `86400` |\n| `FRED_DATAFRAME_DROP_ENABLED` | Set `true` to expose the `fedreserve_dataframe_drop` tool. | `false` |\n| `CANVAS_PROVIDER_TYPE` | Set to `duckdb` to enable DataCanvas SQL querying for observation results. | — |\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). | `/logs` |\n| `STORAGE_PROVIDER_TYPE` | Storage backend. | `in-memory` |\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 federal-reserve-mcp-server .\ndocker run --rm -e FRED_API_KEY=your-key -e MCP_TRANSPORT_TYPE=http -p 3010:3010 federal-reserve-mcp-server\n```\n\nThe Dockerfile defaults to HTTP transport, stateless session mode, and logs to `/var/log/federal-reserve-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 and inits services. |\n| `src/config` | Server-specific environment variable parsing and validation with Zod. |\n| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). Eight tools across FRED domain and DataCanvas. |\n| `src/services/fred` | FRED API service — HTTP client, retry, 429 handling, key injection. |\n| `src/services/canvas-bridge` | DataCanvas adapter — table naming, TTL/provenance tracking, SQL gate extras. |\n| `tests/` | Unit and integration tests mirroring `src/`. |\n| `docs/` | Design and planning documents. |\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 in `src/mcp-server/tools/definitions/index.ts`\n- Wrap FRED API calls: validate raw response → 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",
"bytes": 12042,
"sha": "aa9379dbfd6a154d915cf5c53235ede36845893f85f2f04345d24d61981bb3c4",
"repo_slug": "cyanheads/fred-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_cyanheads_fred_mcp_server_25dd50a3/readme"
}