@cyanheads/federal-reserve-mcp-server
Runs read-only DuckDB SQL (joins, aggregates, window functions, CTEs, range()/generate_series()) over staged FRED observation data held in DataCanvas dataframes, with row limits, inline previews, and the ability to register query results as new dataframes.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 |
| Full-text search across FRED series titles, tags, and notes |
| Fetch metadata for one or more series — title, units, frequency, observation range |
| Fetch date+value observations for one or more series, with date-range and unit-transform filtering |
| Navigate the FRED category tree |
| Look up a FRED release by ID or name search, with its associated series |
| List active DataCanvas dataframes with provenance, schema, and row count |
| Run a SELECT against registered DataCanvas dataframes via DuckDB SQL |
| Drop a DataCanvas dataframe by name (opt-in) |
Related MCP server: self-mcp-server
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_filterPagination 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
nameEach 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 blockedUse
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 stringsActual 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 disabledDrops 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 errorAmbiguous release names return
search_alternativesinstead of a guessEvery dataframe carries
source_tool,query_params, and TTL fieldsWithout 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-serverFor 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 |
| Required. API key from stlouisfed.org. | — |
| Override the FRED API base URL. |
|
| TTL for DataCanvas observation tables, in seconds. |
|
| Set |
|
| Accept up to 100 series IDs, process 10 observation IDs or 50 metadata IDs, and return |
|
| DataCanvas engine for SQL over observation results. Set |
|
| Transport: |
|
| Port for HTTP server. |
|
| HTTP session mode: |
|
| Auth mode: |
|
| Required | — |
| Required | — |
| Log level (RFC 5424). |
|
| Directory for log files (Node.js only). Set an absolute path to put logs outside the server package. |
|
| Storage backend. |
|
| Enable OpenTelemetry instrumentation. |
|
| Base OTLP URL for traces ( | — |
| OTLP log endpoint (logs are off unless set). | — |
| Log failed tool arguments and results with key-name redaction; secrets in free-form values are not redacted. |
|
| Byte cap per logged payload. |
|
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.gitNavigate into the directory:
cd federal-reserve-mcp-serverInstall dependencies:
bun installConfigure environment:
cp .env.example .env
# edit .env and set FRED_API_KEYLocal development
Build and run:
# One-time build bun run rebuild # Run the built server bun run start:stdio # or bun run start:httpRun 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:latestThe 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-serverThe 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 |
|
|
| Server-specific environment variable parsing and validation with Zod. |
| Tool definitions ( |
| FRED API service — HTTP client, retry, 429 handling, key injection. |
| DataCanvas adapter — table naming, TTL/provenance tracking, SQL gate extras. |
| Unit and integration tests mirroring |
| 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 logicUse
ctx.logfor request-scoped logging,ctx.statefor tenant-scoped storageImport new tools directly into
src/index.ts; construct configuration-dependent tools insetup()before registrationWrap 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 testLicense
Apache-2.0 — see LICENSE for details.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Query SEC EDGAR filings, XBRL financials, and company data via MCP. STDIO or Streamable HTTP.
Search NPPES providers and resolve NUCC specialty codes via MCP over STDIO or Streamable HTTP.
Query FDA data on drugs, food, devices, and recalls via openFDA. STDIO or Streamable HTTP.
Fetch US Bureau of Labor Statistics data — CPI, unemployment, wages, JOLTS, and more via MCP.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceAn MCP server that wraps the Federal Reserve Economic Data (FRED) API, providing access to over 800,000 economic time series like GDP and unemployment. It enables AI agents to search for data, retrieve metadata, and fetch historical observations directly from the St. Louis Fed.Apache 2.0
- FlicenseNot gradedqualityDmaintenanceFastMCP server for querying FRED financial and macroeconomic data, providing tools to search and retrieve economic indicators.-
- AlicenseNot gradedqualityBmaintenanceAccess FEC campaign finance data through MCP. Query data about candidates, money trails, and election filings. STDIO & Streamable HTTP.422 npm2Apache 2.0
- AlicenseBqualityBmaintenanceEnables querying and retrieving Federal Reserve Economic Data (FRED) including series, categories, releases, sources, and tags, with support for stdio and HTTP transports and bring-your-own-key authentication.31140 PyPI2MIT