
federal-reserve-mcp-server
io.github.cyanheads/federal-reserve-mcp-server
Search and fetch ~800K Federal Reserve economic time-series from the FRED API via MCP.
Documentation
@cyanheads/federal-reserve-mcp-server
Search and fetch ~800K Federal Reserve economic time-series from the FRED API via MCP. STDIO or Streamable HTTP.
Overview
Economic data from FRED, the St. Louis Fed's database of ~800K time series on output, prices, employment, money, rates, housing, and trade. Search series, pull observations, browse categories and releases, and run SQL over large results.
Tools
| Tool | Description |
|---|---|
fedreserve_search_series | Full-text search across FRED series titles, tags, and notes |
fedreserve_get_series | Fetch metadata for one or more series — title, units, frequency, observation range |
fedreserve_get_observations | Fetch date+value observations for one or more series, with date-range and unit-transform filtering |
fedreserve_browse_categories | Navigate the FRED category tree |
fedreserve_get_release | Look up a FRED release by ID or name search, with its associated series |
fedreserve_dataframe_describe | List active DataCanvas dataframes with provenance, schema, and row count |
fedreserve_dataframe_query | Run a SELECT against registered DataCanvas dataframes via DuckDB SQL |
fedreserve_dataframe_drop | Drop a DataCanvas dataframe by name (opt-in) |
Capability reference
The FRED workflow guide covers indicator comparisons, release schedules, observation paging, and SQL over staged data. It ships with plugin, npm, Docker, and desktop-bundle installs and is available as the MCP resource skill://federal-reserve-guide/SKILL.md.
fedreserve_search_series tool
- Full-text or series-ID search, with
frequency,units,seasonal_adjustment, andtag_namesfilters;filter_variableandfilter_valuemust be supplied together or the call returnsinvalid_filter - Pagination via
limit(default 20, max 1000). FRED accepts a maximum startingoffsetof 4000; useoffset: 4000, limit: 1000for the final search-window page. Narrow the query or add filters to reach matches beyond that window. - Frequency and seasonal-adjustment filter values are trimmed and normalized to FRED's casing; full frequency labels reduce to their base word. Units filters remain exact and case-sensitive.
- Output includes
active_filtersandpopularity(0–100) when available; empty results suggest a broader query or category browsing
fedreserve_get_series tool
- Accepts an ID, comma-separated IDs, or an array; trims, uppercases, and deduplicates IDs. Processes 50 unique IDs and returns the remainder in
deferred_ids(up to 100 supplied IDs by default). - Returns title, units, frequency, seasonal adjustment, observation range, popularity, and notes per series
- Failed IDs in a batch land in a
failedarray with FRED's safe error text; a genuinely missing single ID throwsseries_not_found, while validation and upstream availability errors retain their codes. An entirely failed batch throwspartial_failure. include_release: trueadds the release ID and name for each successful series through one optional bounded lookup. Pass its ID tofedreserve_get_releasefor the schedule; unavailable mappings are disclosed in a notice.
fedreserve_get_observations tool
- Normalizes IDs like
fedreserve_get_series, processes 10 unique IDs, and returns excess IDs indeferred_ids. Acceptsobservation_start/observation_end(YYYY-MM-DD), unit transforms, and frequency downsampling viaaggregation_method(avg,sum,eop). Reversed dates fail before fetching; aggregation without a frequency adds a notice. sort_order(ascby default),limit(1–100000), andoffsetapply upstream to each series. Omitting paging controls retains the full fetch. For the latest three observations, usesort_order: "desc", limit: 3;offset: 3gets the next three.- Returns date/value observations (strings preserve trailing zeros), transform code
units, transform descriptionunits_label, optional nativeseries_units, and per-series failures. An entirely failed batch throwspartial_failure. - Multi-series or >500-row results go to a DataCanvas table with a 20-row preview distributed across series. Previews select the newest fetched rows in the requested order; counts and date bounds describe the entire fetched page. The
noticenamesdataset.nameand executable describe/query calls. Without canvas, the inline preview includes paging guidance. Advance a follow-up offset by each series' fetchedobservation_count, not its preview length.
fedreserve_browse_categories tool
- Omit
category_idto start at the root (ID 0); returns the category and its children. Leaf categories return popularity-descendingsample_series, paged byseries_limit(default 10, max 1000) andseries_offset, plus the upstreamseries_counteven on empty pages. - An unknown
category_idthrowscategory_not_found
fedreserve_get_release tool
- Takes exactly one of
release_idorrelease_search(case-insensitive name substring) - Returns release name, link, notes, the next five scheduled dates, and a popularity-descending series list (
series_limitdefault 20, max 1000;series_offset). A failed optional schedule request setsscheduled_dates_unavailable; an empty successful schedule remains distinct. - An ambiguous name returns up to 10
search_alternatives; retry with the exactrelease_id
fedreserve_dataframe_describe tool
- Lists active DataCanvas dataframes, newest first, or one by
name - Each entry carries
source_tool,query_params,created_at,expires_at,row_count,truncated/max_rows, andcolumn_schema
fedreserve_dataframe_query tool
- Runs one read-only DuckDB SELECT against
df_<id>tables (joins, aggregates, window functions, CTEs); external files, system catalogs, and engine-setting functions are blocked - Use
range()andgenerate_series()with constant arguments. Avoid DuckDB metadata names such asduckdb_tablesfor columns, aliases, CTEs, and staged tables. Qualify a column namedcurrent_schemawith its table alias. row_limitcaps returned rows (default 1000, max 10000) andpreviewsets the inline sample; BIGINT results serialize as strings- Actual provider caps return
truncated: trueand omittotalCountbecause the full count is unknown; a smaller inline preview alone does not imply truncation. Use a narrower query orregister_asto retain the complete result. register_assaves the full result as a new dataframe with its own TTL and materialized DuckDB column types, even whenpreview: 0. SQL NULL values remain distinct from empty strings and the textnullin both response formats.
fedreserve_dataframe_drop tool
- Opt-in: enabled by
FRED_DATAFRAME_DROP_ENABLED=true, otherwise registered as disabled - Drops the named dataframe early; returns
dropped: falsewhen it doesn't exist
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:
- Requires a
FRED_API_KEYfor the FRED API (up to 120 requests/minute) - Unit transforms and frequency downsampling run on FRED's side against the full series history
- Large observation results spill to DataCanvas tables you can query with SQL
- DataCanvas runs on DuckDB by default; with
CANVAS_PROVIDER_TYPE=none, the dataframe tools reportcanvas_unavailable
Agent-friendly output:
- Partial failures:
fedreserve_get_seriesandfedreserve_get_observationsretain successful series and per-ID failures; an entirely failed batch returns an error - Ambiguous release names return
search_alternativesinstead of a guess - Every dataframe carries
source_tool,query_params, and TTL fields - Without DataCanvas,
fedreserve_get_observationsreturns a truncated inline preview with an explanatorymessage
Getting started
Get a free FRED API key, then add the server to Claude Code.
claude mcp add federal-reserve-mcp-server -e FRED_API_KEY=your-api-key -- npx -y @cyanheads/federal-reserve-mcp-server
For other MCP clients, add this to the client's configuration file.
{
"mcpServers": {
"federal-reserve-mcp-server": {
"command": "npx",
"args": ["-y", "@cyanheads/federal-reserve-mcp-server"],
"env": { "FRED_API_KEY": "your-api-key" }
}
}
}
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.
| Variable | Description | Default |
|---|---|---|
FRED_API_KEY | Required. API key from stlouisfed.org. | — |
FRED_BASE_URL | Override the FRED API base URL. | https://api.stlouisfed.org/fred |
FRED_DATASET_TTL_SECONDS | TTL for DataCanvas observation tables, in seconds. | 86400 |
FRED_DATAFRAME_DROP_ENABLED | Set true to enable fedreserve_dataframe_drop; otherwise registered as disabled. | false |
FRED_CLAMP_LIMITS | Accept up to 100 series IDs, process 10 observation IDs or 50 metadata IDs, and return deferred_ids. Set false to reject inputs above those processing limits. | true |
CANVAS_PROVIDER_TYPE | DataCanvas engine for SQL over observation results. Set none to disable it. | duckdb |
MCP_TRANSPORT_TYPE | Transport: stdio or http. | stdio |
MCP_HTTP_PORT | Port for HTTP server. | 3010 |
MCP_SESSION_MODE | HTTP session mode: auto, stateful, or stateless. | stateless |
MCP_AUTH_MODE | Auth mode: none, jwt, or oauth. | none |
MCP_JWT_EXPECTED_AUDIENCE | Required aud claim in JWT mode. An unset value accepts any audience and logs a startup warning. | — |
MCP_JWT_EXPECTED_ISSUER | Required iss claim in JWT mode. Configure it alongside the audience. | — |
MCP_LOG_LEVEL | Log level (RFC 5424). | info |
LOGS_DIR | Directory for log files (Node.js only). Set an absolute path to put logs outside the server package. | <server-package>/logs |
STORAGE_PROVIDER_TYPE | Storage backend. | in-memory |
OTEL_ENABLED | Enable OpenTelemetry instrumentation. | false |
OTEL_EXPORTER_OTLP_ENDPOINT | Base OTLP URL for traces (/v1/traces) and metrics (/v1/metrics). | — |
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT | OTLP log endpoint (logs are off unless set). | — |
LOG_TOOL_FAILURE_PAYLOADS | Log failed tool arguments and results with key-name redaction; secrets in free-form values are not redacted. | false |
LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES | Byte cap per logged payload. | 16384 |
See .env.example for the full list of optional overrides.
SQL over observation tables is on by default; set CANVAS_PROVIDER_TYPE=none to turn it off. npm installs and Docker images include the DuckDB runtime. The Claude Desktop bundle omits native bindings and runs with the canvas off; use the npm or Docker installation for SQL over observations.
Running the server
Prerequisites
- Bun v1.4.4 or higher (or Node.js v24+).
- A free FRED API key from stlouisfed.org. The key grants 120 requests/minute.
Installation
- Clone the repository:
git clone https://github.com/cyanheads/federal-reserve-mcp-server.git
- Navigate into the directory:
cd federal-reserve-mcp-server
- Install dependencies:
bun install
- Configure environment:
cp .env.example .env
# edit .env and set FRED_API_KEY
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 run --rm -e FRED_API_KEY=your-api-key -p 3010:3010 ghcr.io/cyanheads/federal-reserve-mcp-server:latest
The image defaults to Streamable HTTP at http://localhost:3010/mcp. For stdio, run it with -i -e MCP_TRANSPORT_TYPE=stdio and omit the port mapping.
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
| Directory | Purpose |
|---|---|
src/index.ts | createApp() entry point — registers tools and inits services. |
src/config | Server-specific environment variable parsing and validation with Zod. |
src/mcp-server/tools | Tool definitions (*.tool.ts). Eight tools across FRED domain and DataCanvas. |
src/services/fred | FRED API service — HTTP client, retry, 429 handling, key injection. |
src/services/canvas-bridge | DataCanvas adapter — table naming, TTL/provenance tracking, SQL gate extras. |
tests/ | Unit and integration tests mirroring src/. |
docs/ | Design and planning documents. |
Development guide
See CLAUDE.md for development guidelines and architectural rules. The short version:
- Handlers throw, framework catches — no
try/catchin tool logic - Use
ctx.logfor request-scoped logging,ctx.statefor tenant-scoped storage - Import new tools directly into
src/index.ts; construct configuration-dependent tools insetup()before registration - 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.
@cyanheads/federal-reserve-mcp-servernpm install @cyanheads/federal-reserve-mcp-server@cyanheads/federal-reserve-mcp-servernpm install @cyanheads/federal-reserve-mcp-serverRelated Servers
io.github.cyanheads/anime-mcp-server
Search anime/manga, franchise relations, schedule, characters, rankings, studio filmography.
io.github.cyanheads/art-institute-chicago-mcp-server
Search the Art Institute of Chicago collection: artworks, artists, exhibitions, and audio guides.
io.github.cyanheads/arxiv-mcp-server
Search arXiv, fetch paper metadata, and read full-text content.