@cyanheads/federal-reserve-mcp-server

Overview

Federal Reserve economic data from the FRED API (Federal Reserve Bank of St. Louis) — ~800K time series covering output, prices, employment, money, rates, housing, trade, and international macro. Search series, fetch metadata and observations, browse the category tree, look up releases, and query large result sets with SQL over DataCanvas. Runs as a stdio process or a local Streamable HTTP server.

Tools

Related MCP server: self-mcp-server

Capability reference

fedreserve_search_series tool

• Full-text (default) or series-ID search mode; optional post-search filter by frequency, units, or seasonal_adjustment, plus semicolon-delimited tag_names

• Pagination via limit (max 1000, default 1000) and offset (max 4999 — FRED caps searchable results at 5000)

• Output echoes active_filters when any were applied, and a popularity score (0–100) when FRED provides one

• Empty results suggest broadening the query or using fedreserve_browse_categories; for a specific release's series, use fedreserve_get_release instead

fedreserve_get_series tool

• Accepts a single series ID or up to 50 in one call; fires parallel upstream requests (no FRED batch endpoint exists)

• Returns title, units, frequency, seasonal adjustment, observation range, popularity, and notes per series

• Partial-batch failures land in a failed array with per-ID error messages; a single unresolved ID throws series_not_found instead

fedreserve_get_observations tool

• Accepts a single series ID or up to 10 in one call, one upstream request per series in parallel

• Date-range filtering (observation_start / observation_end, ISO 8601) and FRED's native unit transforms (lin, chg, ch1, pch, pc1, pca, cch, cca, log)

• Frequency downsampling (daily through annual, plus weekly-ending variants) with aggregation_method (avg, sum, eop)

• Multi-series or >500-row results spill to a DataCanvas table — the response carries a dataset.name handle for fedreserve_dataframe_query; degrades to a truncated inline preview when canvas is unavailable

• Values stay strings to preserve trailing zeros

fedreserve_browse_categories tool

• Omit category_id to start at the root (ID 0); returns the category, its child categories, and — for a leaf with no children — a sample of up to 10 series

• An unknown category_id throws category_not_found

fedreserve_get_release tool

• Exactly one of release_id (integer) or release_search (case-insensitive substring, filtered client-side — FRED has no server-side release search) is required

• Returns release name, link, notes, upcoming scheduled dates, and a paginated series list (series_limit max 1000, series_offset)

• An ambiguous name search returns up to 10 search_alternatives instead of guessing; retry with the exact release_id

fedreserve_dataframe_describe tool

• Lists all active DataCanvas dataframes for the tenant, or one by name, newest first

• Each entry carries source_tool, query_params, created_at, a sliding expires_at, row_count, truncated / max_rows, and full column_schema

• Requires CANVAS_PROVIDER_TYPE=duckdb; throws canvas_unavailable otherwise

fedreserve_dataframe_query tool

• Single-statement SELECT only, against df_<id> tables from fedreserve_get_observations — joins, aggregates, window functions, and CTEs supported; writes, DDL, DROP, COPY, PRAGMA, ATTACH, external-file table functions, and system catalogs are rejected

• row_limit caps materialized rows (default 1000, max 10000); preview controls how many are returned inline

• Optional register_as persists the result as a new dataframe with its own TTL, for chaining without re-running the source SQL

• BIGINT columns (COUNT/SUM) serialize as JSON strings — cast to DOUBLE for inline arithmetic

• Requires CANVAS_PROVIDER_TYPE=duckdb; throws canvas_unavailable otherwise

fedreserve_dataframe_drop tool

• Opt-in — only registered when FRED_DATAFRAME_DROP_ENABLED=true; otherwise listed as a disabled tool card

• Idempotent: returns dropped: false when the named table doesn't exist, rather than erroring

• TTL already reclaims expired tables automatically — this tool is for explicit early cleanup

• Requires CANVAS_PROVIDER_TYPE=duckdb; throws canvas_unavailable otherwise

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.

FRED-specific:

• FRED_API_KEY-gated access to the St. Louis Fed's FRED API (api.stlouisfed.org/fred) at up to 120 requests/minute

• Parallel multi-series fetching via Promise.allSettled, with partial success reported per ID rather than failing the whole batch

• DataCanvas spillover for multi-series or >500-row observation results, queryable via fedreserve_dataframe_query

• FRED's native unit transformations and frequency downsampling delegated server-side for precision against the full series history

• Category tree navigation across all FRED domains — Money & Banking, National Accounts, Employment, Prices, Housing, Trade, and more

Agent-friendly output:

• Graceful partial failure — fedreserve_get_series and fedreserve_get_observations return per-ID failed rows with error messages instead of failing the whole request

• Ambiguous-input disambiguation — fedreserve_get_release's name search returns typed search_alternatives instead of guessing when multiple releases match

• Provenance on DataCanvas output — every dataframe carries source_tool, query_params, and TTL fields so agents can reason about where staged data came from and how long it's valid

• Degrades gracefully — fedreserve_get_observations falls back to a truncated inline preview with an explanatory message when DataCanvas isn't configured, rather than failing

Getting started

Add the following to your MCP client configuration file. Obtain a free FRED API key at research.stlouisfed.org/docs/api/api_key.html.

{
  "mcpServers": {
    "federal-reserve-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/federal-reserve-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "FRED_API_KEY": "your-api-key"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "federal-reserve-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/federal-reserve-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "FRED_API_KEY": "your-api-key"
      }
    }
  }
}

Or with Docker:

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

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 FRED_API_KEY=... bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

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

• A free FRED API key from stlouisfed.org. The key grants 120 requests/minute.

Installation

1. Clone the repository:

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

2. Navigate into the directory:

cd federal-reserve-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# edit .env and set FRED_API_KEY

Configuration

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

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 federal-reserve-mcp-server .
docker run --rm -e FRED_API_KEY=your-key -e MCP_TRANSPORT_TYPE=http -p 3010:3010 federal-reserve-mcp-server

The 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.

Project structure

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 in src/mcp-server/tools/definitions/index.ts

• Wrap FRED API calls: validate raw response → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.