This server provides access to over 800,000 Federal Reserve Economic Data (FRED) time series through three core tools:
Browse the complete FRED catalog using fred_browse to navigate categories, releases, sources, and their associated series with pagination and sorting options
Search for specific economic data series using fred_search with keywords, tags, full-text or series ID searches, and filters by frequency, units, or seasonal adjustment
Retrieve time series data using fred_get_series with powerful features including:
Date range filtering
Data transformations (levels, changes, percent changes, logs, compounded rates)
Frequency aggregation (daily, weekly, monthly, quarterly, annual)
Multiple aggregation methods (average, sum, end of period)
Vintage data access for historical revisions
Pagination support (up to 1,000 results for browsing/searching, up to 100,000 observations for series data)
Access real-time economic indicators including GDP, unemployment, inflation, interest rates, and hundreds of thousands of other metrics. Deploy flexibly via Claude Desktop, Docker, or HTTP transport for network-based access.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Federal Reserve Economic Data (FRED) MCP Server find the latest US unemployment rate data"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Disclaimer: This open-source project is not affiliated with, sponsored by, or endorsed by the Federal Reserve or the Federal Reserve Bank of St. Louis. "FRED" is a registered trademark of the Federal Reserve Bank of St. Louis, used here for descriptive purposes only.
A Model Context Protocol (MCP) server providing universal access to all 800,000+ Federal Reserve Economic Data (FRED®) time series through three powerful tools.
https://github.com/user-attachments/assets/66c7f3ad-7b0e-4930-b1c5-a675a7eb1e09
If you use this project in your research or work, please cite it using theCITATION.cff file, or use the following citation:
APA Format:
Amorelli, S. (2025). Federal Reserve Economic Data MCP (Model Context Protocol) Server (Version 1.0.2) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.14536707BibTeX:
@software{amorelli_2025_14536707,
author = {Amorelli, Stefano},
title = {{Federal Reserve Economic Data MCP (Model Context
Protocol) Server}},
month = jan,
year = 2025,
publisher = {Zenodo},
version = {1.0.2},
doi = {10.5281/zenodo.14536707},
url = {https://doi.org/10.5281/zenodo.14536707}
}Clone the repository:
git clone https://github.com/stefanoamorelli/fred-mcp-server.git
cd fred-mcp-serverInstall dependencies:
pnpm installBuild the project:
pnpm buildRelated MCP server: FRED MCP Server
This server requires a FRED® API key. You can obtain one from the FRED® website.
Install the server, for example, on Claude Desktop, modify the claude_desktop_config.json file and add the following configuration:
{
"mcpServers": {
"FRED MCP Server": {
"command": "/usr/bin/node",
"args": [
"<PATH_TO_YOUR_CLONED_REPO>/fred-mcp-server/build/index.js"
],
"env": {
"FRED_API_KEY": "<YOUR_API_KEY>"
}
}
}
}You can also run the FRED MCP Server using Docker. Add this configuration to your claude_desktop_config.json:
{
"mcpServers": {
"fred-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"FRED_API_KEY=<your-key-here>",
"stefanoamorelli/fred-mcp-server:latest"
],
"env": {}
}
}
}Replace <your-key-here> with your actual FRED API key.
For network deployments, you can run the server with Streamable HTTP transport instead of stdio:
# Using CLI flag
node build/index.js --http
# Or using environment variable
TRANSPORT=http node build/index.js
# Custom port (default is 3000)
PORT=8080 node build/index.js --httpThe server will be available at http://localhost:3000/mcp (or your custom port).
Example client request:
# Initialize session
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}'
# Use the mcp-session-id from the response header for subsequent requests
curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "mcp-session-id: <session-id-from-init>" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'A GET /healthz endpoint reports active sessions, cache statistics, and uptime for load balancers and orchestrators.
All settings are environment variables with sensible defaults:
Variable | Default | Description |
| (required) | Your FRED API key |
|
| Per-request timeout against the FRED API |
|
| Retries for 429/5xx/network failures (exponential backoff with jitter, honors |
|
| Base delay for retry backoff |
|
| Client-side token bucket matching FRED's per-key quota |
|
| TTL for cached API responses ( |
|
| LRU cache capacity |
|
| Set to |
| (all interfaces) | HTTP bind address |
|
| HTTP port |
|
| Maximum concurrent MCP sessions (new sessions get |
|
| Idle time before a session is reaped |
|
| How often the idle-session reaper runs |
|
| Maximum accepted JSON body size |
|
|
|
Identical concurrent requests are coalesced into a single upstream call, and successful responses are cached, so multiple sessions share one rate-limit budget efficiently.
This MCP server provides three comprehensive tools to access all 800,000+ FRED® economic data series:
fred_browseDescription: Browse FRED's complete catalog through categories, releases, or sources.
Parameters:
browse_type (required): Type of browsing - "categories", "releases", "sources", "category_series", "release_series"
category_id (optional): Category ID for browsing subcategories or series within a category
release_id (optional): Release ID for browsing series within a release
limit (optional): Maximum number of results (default: 50)
offset (optional): Number of results to skip for pagination
order_by (optional): Field to order results by
sort_order (optional): "asc" or "desc"
fred_searchDescription: Search for FRED economic data series by keywords, tags, or filters.
Parameters:
search_text (optional): Text to search for in series titles and descriptions
search_type (optional): "full_text" or "series_id"
tag_names (optional): Comma-separated list of tag names to filter by
exclude_tag_names (optional): Comma-separated list of tag names to exclude
limit (optional): Maximum number of results (default: 25)
offset (optional): Number of results to skip for pagination
order_by (optional): Field to order by (e.g., "popularity", "last_updated")
sort_order (optional): "asc" or "desc"
filter_variable (optional): Filter by "frequency", "units", or "seasonal_adjustment"
filter_value (optional): Value to filter the variable by
fred_get_seriesDescription: Retrieve data for any FRED series by its ID with support for transformations and date ranges.
Parameters:
series_id (required): The FRED series ID (e.g., "GDP", "UNRATE", "CPIAUCSL")
observation_start (optional): Start date in YYYY-MM-DD format
observation_end (optional): End date in YYYY-MM-DD format
limit (optional): Maximum number of observations
offset (optional): Number of observations to skip
sort_order (optional): "asc" or "desc"
units (optional): Data transformation:
"lin" (levels/no transformation)
"chg" (change from previous period)
"ch1" (change from year ago)
"pch" (percent change)
"pc1" (percent change from year ago)
"pca" (compounded annual rate of change)
"cch" (continuously compounded rate of change)
"log" (natural log)
frequency (optional): Frequency aggregation ("d", "w", "m", "q", "a")
aggregation_method (optional): "avg" (average), "sum", or "eop" (end of period)
With these three tools, you can:
Browse all economic categories and discover available data
Search for specific indicators by keywords or tags
Retrieve any of the 800,000+ series with custom transformations
Access real-time economic data including GDP, unemployment, inflation, interest rates, and more
Want to be featured? TagStefano Amorelli on LinkedIn or @stefanoamorelli on X in your post about using FRED MCP Server, or submit a PR to add your shoutout!
We're grateful for the community support! Here are some mentions from amazing people:
See TESTING.md for more details.
# Run all tests
pnpm test
# Run specific tests
pnpm test:registryThis open-source project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). This means:
You can use, modify, and distribute this software
If you modify and distribute it, you must release your changes under AGPL-3.0
If you run a modified version on a server, you must provide the source code to users
See the LICENSE file for full details
For commercial licensing options or other licensing inquiries, please contact stefano@amorelli.tech.
© 2025 Stefano Amorelli
Browse FRED's complete catalog through categories, releases, or sources. Use browse_type='categories' to explore the category tree, 'releases' for data releases, 'sources' for data sources, 'category_series' to get all series in a category, or 'release_series' to get all series in a release.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results | |
| offset | No | Number of results to skip | |
| order_by | No | Field to order by | |
| release_id | No | Release ID (for release_series) | |
| sort_order | No | Sort order | |
| browse_type | Yes | Type of browsing to perform | |
| category_id | No | Category ID (for categories or category_series) | |
| filter_value | No | Value to filter the variable by (category_series only) | |
| filter_variable | No | Variable to filter by (category_series only) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden of disclosing behavioral traits. However, it only states that browsing is possible through categories/allows/releases/sources; it does not explicitly state that this is read-only, does not mention pagination behavior, rate limits, return format, or contextual dependencies. Though the word 'browse' implies a read operation, key behavioral expectations remain unstated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero fluff. The first sentence gives a high-level summary, and the second defines each browse_type in a compact list. It is front-loaded and necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 9 parameters, no output schema, and no annotations, the description does a solid job of covering the main polymorphic behavior via browse_type. However, it does not address pagination via limit/offset or how filter parameters relate to actual output, though the schema fills some gaps. It is slightly incomplete for full contextual coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, giving a baseline of 3. The description adds semantic meaning by explaining exactly what each browse_type enum does (e.g., 'category_series' returns all series in a category), which is not fully embedded in the parameter schema's short string description. This goes beyond the schema and meaningfully guides parameter selection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb (browse) and resource (FRED's complete catalog), and enumerates the distinct browsing modes: categories, releases, sources, category_series, and release_series. This clearly differentiates it from sibling tools like fred_search and fred_get_series by emphasizing catalog exploration vs searching or retrieving a single series.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for using the tool to explore FRED's catalog and details each browse_type variant, but it does not explicitly compare with fred_search or fred_get_series or state when not to use this tool. Since it gives clear operational guidance for internal parameter choices, it meets the 'clear context, no exclusions' bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve data for any FRED series by its ID. Supports data transformations, frequency changes, and date ranges.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of observations to return | |
| units | No | Data transformation: lin=levels, chg=change, pch=percent change, log=natural log | |
| offset | No | Number of observations to skip | |
| frequency | No | Frequency aggregation: d=daily, w=weekly, m=monthly, q=quarterly, a=annual | |
| series_id | Yes | The FRED series ID to retrieve data for (e.g., 'GDP', 'UNRATE', 'CPIAUCSL') | |
| sort_order | No | Sort order of observations by date | |
| output_type | No | Output format: 1=observations, 2=observations by vintage, 3=observations by release, 4=initial release only | |
| vintage_dates | No | Vintage date or dates in YYYY-MM-DD format | |
| observation_end | No | End date for observations in YYYY-MM-DD format | |
| observation_start | No | Start date for observations in YYYY-MM-DD format | |
| aggregation_method | No | Aggregation method: avg=average, sum=sum, eop=end of period |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It simply says 'Retrieve data' without stating side effects, limitations, rate limits, output structure, or error conditions. For a read operation, it's not harmful but inadequately informative about what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, no redundant phrasing. Every word earns its place, but it is perhaps too sparse (under-specified) rather than genuinely concise—still, it is well-structured and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 11 parameters, several with enums, and no output schema. The description provides no information about return formats, required fields beyond the implied series_id, or how to interpret transformations/frequencies. This is insufficient for an agent to confidently select and use the tool without relying heavily on the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already describes each parameter in detail. The description mentions transformations, frequency, and date ranges, which loosely map to units, frequency, and observation_start/end, but adds no new meaning beyond what the schema provides. The baseline of 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves data for a FRED series by its ID, which is a specific verb and resource. It does not explicitly differentiate from siblings (fred_browse, fred_search), but the intent is unambiguous—getting the actual data series rather than browsing or searching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage—use this to get series data—but provides no explicit guidance on when to choose this over fred_browse or fred_search, nor any exclusions or prerequisites. The mention of supported options (transformations, frequency, date ranges) gives some context but no decision framework.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for FRED economic data series by keywords, tags, or filters. Returns matching series with their IDs, titles, and metadata. Use this to find specific series when you know what you're looking for.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results to return | |
| offset | No | Number of results to skip for pagination | |
| order_by | No | Field to order results by | |
| tag_names | No | Comma-separated list of tag names to filter by | |
| sort_order | No | Sort order for results | |
| search_text | No | Text to search for in series titles and descriptions | |
| search_type | No | Type of search to perform | |
| filter_value | No | Value to filter the variable by | |
| filter_variable | No | Variable to filter by | |
| exclude_tag_names | No | Comma-separated list of tag names to exclude |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It states it returns series with IDs, titles, and metadata, but does not disclose pagination behavior, the two search types (full_text vs series_id), or any rate limits. This is a significant gap for a tool with 10 parameters and no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, all relevant, with the most important information front-loaded. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters, no output schema, and no annotations, the description is too sparse. It lacks explanation of search types, pagination usage, ordering behavior, and any practical examples. An agent would need more guidance to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds slight value by mapping 'keywords, tags, or filters' to search_text, tag_names, and filter_variable/filter_value, but does not explain other parameters like order_by or search_type beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it searches for FRED economic data series by keywords, tags, or filters, and returns IDs, titles, and metadata. This distinguishes it from sibling tools fred_browse and fred_get_series, as it's search-oriented rather than browsing or direct retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using this tool when you know what you're looking for, providing clear context for when it applies. However, it does not mention when to use alternatives (fred_browse or fred_get_series) or provide exclusions, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.2.0fred_browse2 fields changedInput schema / properties / filter_valueAdded value: +{
+ "description": "Value to filter the variable by (category_series only)",
+ "type": "string"
+}Input schema / properties / filter_variableAdded value: +{
+ "description": "Variable to filter by (category_series only)",
+ "enum": [
+ "frequency",
+ "units",
+ "seasonal_adjustment"
+ ],
+ "type": "string"
+}v1.0.1fred_browse1 field changedInput schema / additionalPropertiesRemoved value: -falsefred_get_series1 field changedInput schema / additionalPropertiesRemoved value: -falsefred_search1 field changedInput schema / additionalPropertiesRemoved value: -falsefred_browsefred_get_seriesfred_searchEach tool serves a distinct purpose: browsing catalog structure, searching for series, and retrieving series data. There is no overlap or ambiguity between browse, search, and get_series.
All tools follow the consistent pattern fred_<verb>, with descriptive action names: browse, search, get_series. Naming is uniform and predictable.
Three tools cover the core FRED workflow of exploring, finding, and retrieving economic data. The count is minimal but well-scoped for the server's purpose, avoiding unnecessary bloat.
The tool set covers the essential operations: browse the catalog, search for series, and retrieve data. Minor gaps exist such as fetching detailed metadata for a specific series or category, but these are not critical for standard use cases.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
GDP, unemployment, CPI, interest rates, and 800K+ economic time series from the Federal Reserve
Macro data for AI agents: GDP, inflation, unemployment and more (World Bank, US BLS). No keys.
Macro data for AI agents: GDP, inflation, unemployment and more (World Bank, US BLS). No keys.
Equip AI with tools for researching economic data from Federal Reserve Economic Data (FRED).
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/stefanoamorelli/fred-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
