{
  "markdown": "# Federal Reserve Economic Data MCP Server\n\n[![npm version](https://img.shields.io/npm/v/fred-mcp-server.svg)](https://www.npmjs.com/package/fred-mcp-server)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.14536707.svg)](https://doi.org/10.5281/zenodo.14536707)\n[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)\n[![Tests](https://github.com/stefanoamorelli/fred-mcp-server/actions/workflows/test.yml/badge.svg)](https://github.com/stefanoamorelli/fred-mcp-server/actions/workflows/test.yml)\n[![Documentation](https://img.shields.io/badge/docs-fred--mcp--server.amorelli.tech-blue)](https://fred-mcp-server.amorelli.tech)\n\n> [!IMPORTANT]\n> *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.\n\nA Model Context Protocol (`MCP`) server providing universal access to all 800,000+ Federal Reserve Economic Data ([FRED®](https://fred.stlouisfed.org/)) time series through three powerful tools.\n\nhttps://github.com/user-attachments/assets/66c7f3ad-7b0e-4930-b1c5-a675a7eb1e09\n\n> [!TIP]\n> If you use this project in your research or work, please cite it using the [CITATION.cff](CITATION.cff) file, or use the following citation:\n\n**APA Format:**\n```\nAmorelli, S. (2025). Federal Reserve Economic Data MCP (Model Context Protocol) Server (Version 1.0.2) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.14536707\n```\n\n**BibTeX:**\n```bibtex\n@software{amorelli_2025_14536707,\n  author       = {Amorelli, Stefano},\n  title        = {{Federal Reserve Economic Data MCP (Model Context\n                   Protocol) Server}},\n  month        = jan,\n  year         = 2025,\n  publisher    = {Zenodo},\n  version      = {1.0.2},\n  doi          = {10.5281/zenodo.14536707},\n  url          = {https://doi.org/10.5281/zenodo.14536707}\n}\n```\n\n\n## Installation\n\n### Manual Installation\n\n1.  Clone the repository:\n    ```bash\n    git clone https://github.com/stefanoamorelli/fred-mcp-server.git\n    cd fred-mcp-server\n    ```\n2.  Install dependencies:\n    ```bash\n    pnpm install\n    ```\n3.  Build the project:\n    ```bash\n    pnpm build\n    ```\n\n## Configuration\n\nThis server requires a FRED® API key. You can obtain one from the [FRED® website](https://fred.stlouisfed.org/docs/api/api_key.html).\n\nInstall the server, for example, on [Claude Desktop](https://claude.ai/download), modify the `claude_desktop_config.json` file and add the following configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"FRED MCP Server\": {\n      \"command\": \"/usr/bin/node\",\n      \"args\": [\n        \"<PATH_TO_YOUR_CLONED_REPO>/fred-mcp-server/build/index.js\"\n      ],\n      \"env\": {\n        \"FRED_API_KEY\": \"<YOUR_API_KEY>\"\n      }\n    }\n  }\n}\n```\n\n### Using Docker\n\nYou can also run the FRED MCP Server using Docker. Add this configuration to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"fred-mcp\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"-i\",\n        \"--rm\",\n        \"-e\",\n        \"FRED_API_KEY=<your-key-here>\",\n        \"stefanoamorelli/fred-mcp-server:latest\"\n      ],\n      \"env\": {}\n    }\n  }\n}\n```\n\nReplace `<your-key-here>` with your actual FRED API key.\n\n### Using Streamable HTTP Transport\n\nFor network deployments, you can run the server with Streamable HTTP transport instead of stdio:\n\n```bash\n# Using CLI flag\nnode build/index.js --http\n\n# Or using environment variable\nTRANSPORT=http node build/index.js\n\n# Custom port (default is 3000)\nPORT=8080 node build/index.js --http\n```\n\nThe server will be available at `http://localhost:3000/mcp` (or your custom port).\n\n**Example client request:**\n```bash\n# Initialize session\ncurl -X POST http://localhost:3000/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Accept: application/json, text/event-stream\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"my-client\",\"version\":\"1.0.0\"}}}'\n\n# Use the mcp-session-id from the response header for subsequent requests\ncurl -X POST http://localhost:3000/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Accept: application/json, text/event-stream\" \\\n  -H \"mcp-session-id: <session-id-from-init>\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\"}'\n```\n\nA `GET /healthz` endpoint reports active sessions, cache statistics, and uptime for load balancers and orchestrators.\n\n### Configuration\n\nAll settings are environment variables with sensible defaults:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `FRED_API_KEY` | (required) | Your FRED API key |\n| `FRED_API_TIMEOUT_MS` | `30000` | Per-request timeout against the FRED API |\n| `FRED_API_MAX_RETRIES` | `3` | Retries for 429/5xx/network failures (exponential backoff with jitter, honors `Retry-After`) |\n| `FRED_API_RETRY_BASE_DELAY_MS` | `500` | Base delay for retry backoff |\n| `FRED_RATE_LIMIT_PER_MINUTE` | `120` | Client-side token bucket matching FRED's per-key quota |\n| `FRED_CACHE_TTL_MS` | `60000` | TTL for cached API responses (`0` disables caching) |\n| `FRED_CACHE_MAX_ENTRIES` | `500` | LRU cache capacity |\n| `TRANSPORT` | `stdio` | Set to `http` for Streamable HTTP transport |\n| `HOST` | (all interfaces) | HTTP bind address |\n| `PORT` | `3000` | HTTP port |\n| `MCP_MAX_SESSIONS` | `100` | Maximum concurrent MCP sessions (new sessions get `503` beyond this) |\n| `MCP_SESSION_TTL_MS` | `1800000` | Idle time before a session is reaped |\n| `MCP_SESSION_SWEEP_INTERVAL_MS` | `60000` | How often the idle-session reaper runs |\n| `MCP_BODY_LIMIT` | `1mb` | Maximum accepted JSON body size |\n| `LOG_LEVEL` | `info` | `error`, `warn`, `info`, or `debug` (logs go to stderr) |\n\nIdentical concurrent requests are coalesced into a single upstream call, and successful responses are cached, so multiple sessions share one rate-limit budget efficiently.\n\n## Available Tools\n\nThis MCP server provides three comprehensive tools to access all 800,000+ FRED® economic data series:\n\n### `fred_browse`\n\n**Description**: Browse FRED's complete catalog through categories, releases, or sources.\n\n**Parameters**:\n* `browse_type` (required): Type of browsing - \"categories\", \"releases\", \"sources\", \"category_series\", \"release_series\"\n* `category_id` (optional): Category ID for browsing subcategories or series within a category\n* `release_id` (optional): Release ID for browsing series within a release\n* `limit` (optional): Maximum number of results (default: 50)\n* `offset` (optional): Number of results to skip for pagination\n* `order_by` (optional): Field to order results by\n* `sort_order` (optional): \"asc\" or \"desc\"\n\n### `fred_search`\n\n**Description**: Search for FRED economic data series by keywords, tags, or filters.\n\n**Parameters**:\n* `search_text` (optional): Text to search for in series titles and descriptions\n* `search_type` (optional): \"full_text\" or \"series_id\"\n* `tag_names` (optional): Comma-separated list of tag names to filter by\n* `exclude_tag_names` (optional): Comma-separated list of tag names to exclude\n* `limit` (optional): Maximum number of results (default: 25)\n* `offset` (optional): Number of results to skip for pagination\n* `order_by` (optional): Field to order by (e.g., \"popularity\", \"last_updated\")\n* `sort_order` (optional): \"asc\" or \"desc\"\n* `filter_variable` (optional): Filter by \"frequency\", \"units\", or \"seasonal_adjustment\"\n* `filter_value` (optional): Value to filter the variable by\n\n### `fred_get_series`\n\n**Description**: Retrieve data for any FRED series by its ID with support for transformations and date ranges.\n\n**Parameters**:\n* `series_id` (required): The FRED series ID (e.g., \"GDP\", \"UNRATE\", \"CPIAUCSL\")\n* `observation_start` (optional): Start date in YYYY-MM-DD format\n* `observation_end` (optional): End date in YYYY-MM-DD format\n* `limit` (optional): Maximum number of observations\n* `offset` (optional): Number of observations to skip\n* `sort_order` (optional): \"asc\" or \"desc\"\n* `units` (optional): Data transformation:\n  - \"lin\" (levels/no transformation)\n  - \"chg\" (change from previous period)\n  - \"ch1\" (change from year ago)\n  - \"pch\" (percent change)\n  - \"pc1\" (percent change from year ago)\n  - \"pca\" (compounded annual rate of change)\n  - \"cch\" (continuously compounded rate of change)\n  - \"log\" (natural log)\n* `frequency` (optional): Frequency aggregation (\"d\", \"w\", \"m\", \"q\", \"a\")\n* `aggregation_method` (optional): \"avg\" (average), \"sum\", or \"eop\" (end of period)\n\n## Example Usage\n\nWith these three tools, you can:\n- Browse all economic categories and discover available data\n- Search for specific indicators by keywords or tags\n- Retrieve any of the 800,000+ series with custom transformations\n- Access real-time economic data including GDP, unemployment, inflation, interest rates, and more\n\n## Social Media Shoutouts 📣\n\n> [!NOTE]\n> Want to be featured? Tag [Stefano Amorelli](https://www.linkedin.com/in/stefanoamorelli/) on LinkedIn or [@stefanoamorelli](https://x.com/stefanoamorelli) on X in your post about using FRED MCP Server, or [submit a PR](https://github.com/stefanoamorelli/fred-mcp-server/pulls) to add your shoutout!\n\nWe're grateful for the community support! Here are some mentions from amazing people:\n\n<details open>\n<summary><b>Scott G</b> - \"One of my breakthrough moments for 'getting' what is possible with Claude was this fred-mcp-server project...\"</summary>\n<br>\n<a href=\"https://www.linkedin.com/posts/sgoley_as-many-of-us-continue-to-use-llms-more-and-activity-7372401049669885952-ha6M\">\n  <img src=\"assets/social/linkedin-sgoley.jpg\" alt=\"LinkedIn post by Scott G - Fintech & Data Analytics Professional\" width=\"600\">\n</a>\n<br>\n<i>Scott G - Fintech & Data Analytics Professional</i> | <a href=\"https://www.linkedin.com/in/sgoley/\">LinkedIn Profile</a>\n</details>\n\n<details open>\n<summary><b>John Shelburne</b> - \"The FRED MCP Server is a game-changer for financial analysis...\"</summary>\n<br>\n<a href=\"https://www.linkedin.com/posts/shelburne_ai-finance-innovation-activity-7341141860880478210-JQe4\">\n  <img src=\"assets/social/linkedin-john-shelburne.jpg\" alt=\"LinkedIn post by John Shelburne\" width=\"600\">\n</a>\n<br>\n<i>John Shelburne - Fixed Income Fintech Leader with 20+ Years of Experience | Machine Learning & Cloud Computing Specialist</i> | <a href=\"https://www.linkedin.com/in/shelburne/\">LinkedIn Profile</a>\n</details>\n\n<!-- Add more social media posts here using the format above -->\n\n## Testing\n\nSee [TESTING.md](./TESTING.md) for more details.\n\n```bash\n# Run all tests\npnpm test\n\n# Run specific tests\npnpm test:registry\n```\n\n## License ⚖️\n\nThis open-source project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). This means:\n\n- You can use, modify, and distribute this software\n- If you modify and distribute it, you must release your changes under AGPL-3.0\n- If you run a modified version on a server, you must provide the source code to users\n- See the [LICENSE](LICENSE) file for full details\n\nFor commercial licensing options or other licensing inquiries, please contact [stefano@amorelli.tech](mailto:stefano@amorelli.tech).\n\n© 2025 [Stefano Amorelli](https://amorelli.tech)\n",
  "bytes": 11317,
  "sha": "ae7b581e73cc86628dd22e72cd44d9b365f057f25ec71ef693f637a844676e7f",
  "repo_slug": "stefanoamorelli/fred-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_stefanoamorelli_fred_mcp_serve_6022af1c/readme"
}