{"id":27004149,"url":"https://github.com/jaldekoa/mcp-fredapi","last_synced_at":"2025-06-13T16:32:41.355Z","repository":{"id":285981149,"uuid":"959996052","full_name":"Jaldekoa/mcp-fredapi","owner":"Jaldekoa","description":"FRED (Federal Reserve Economic Data) API integration with Model Context Protocol (MCP)","archived":false,"fork":false,"pushed_at":"2025-04-03T17:34:42.000Z","size":0,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-03T17:37:41.117Z","etag":null,"topics":["finance","fred","fred-api","llm","llms","mcp","mcp-server"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Jaldekoa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-04-03T17:31:33.000Z","updated_at":"2025-04-03T17:34:45.000Z","dependencies_parsed_at":"2025-04-03T17:47:48.123Z","dependency_job_id":null,"html_url":"https://github.com/Jaldekoa/mcp-fredapi","commit_stats":null,"previous_names":["jaldekoa/mcp-fredapi"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jaldekoa%2Fmcp-fredapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jaldekoa%2Fmcp-fredapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jaldekoa%2Fmcp-fredapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jaldekoa%2Fmcp-fredapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Jaldekoa","download_url":"https://codeload.github.com/Jaldekoa/mcp-fredapi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247128753,"owners_count":20888235,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["finance","fred","fred-api","llm","llms","mcp","mcp-server"],"created_at":"2025-04-04T06:15:11.219Z","updated_at":"2025-04-09T17:04:37.497Z","avatar_url":"https://github.com/Jaldekoa.png","language":"Python","funding_links":[],"categories":["Finance \u0026 Fintech"],"sub_categories":["How to Submit"],"readme":"# MCP-FREDAPI\n\n**FRED (Federal Reserve Economic Data) API integration with Model Context Protocol (MCP)**\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [Installation](#installation)\n- [Configuration](#configuration)\n  - [FRED API Key](#fred-api-key)\n  - [Claude/Cursor Configuration](#claudecursor-configuration)\n- [Available Tools](#available-tools)\n- [Parameters](#parameters)\n- [Examples](#examples)\n  - [Common Economic Series IDs](#common-economic-series-ids)\n- [Contributing](#contributing)\n- [License](#license)\n- [References](#references)\n\n## Introduction\n\nMCP-FREDAPI provides access to economic data from the Federal Reserve Bank of St. Louis (FRED) through the Model Context Protocol. This integration allows AI assistants like Claude to retrieve economic time series data directly when used with Cursor or other MCP-compatible environments.\n\nThis package integrates with the [official FRED API](https://fred.stlouisfed.org/docs/api/fred/), focusing specifically on the [series_observations endpoint](https://fred.stlouisfed.org/docs/api/fred/series_observations.html) which provides time series data for economic indicators.\n\n## Installation\n\nThere are two installation methods:\n\n### Method 1: Using pip\n\nInstall the required dependencies:\n\n```terminal\npip install \"mcp[cli]\" httpx python-dotenv\n```\n\nClone this repository:\n\n```terminal\ngit clone https://github.com/Jaldekoa/mcp-fredapi.git\ncd mcp-fredapi\n```\n\n### Method 2: Using uv (Recommended)\n\nThis method is recommended as it matches the configuration shown in mcp.json.\n\n1. First, install uv if you don't have it yet:\n\n```terminal\npip install uv\n```\n\n2. Clone this repository:\n\n```terminal\ngit clone https://github.com/Jaldekoa/mcp-fredapi.git\ncd mcp-fredapi\n```\n\n3. Use uv to run the server (no need to install dependencies separately):\n\n```terminal\nuv run --with mcp --with httpx mcp run server.py\n```\n\n## Configuration\n\n### FRED API Key\n\nYou'll need a FRED API key, which you can obtain from [FRED API](https://fred.stlouisfed.org/docs/api/api_key.html).\n\nCreate a `.env` file in the project root:\n\n```\nFRED_API_KEY=your_api_key_here\n```\n\n### Claude/Cursor Configuration\n\nTo configure Cursor to use this MCP server, add the following to your `~/.cursor/mcp.json` file:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-fredapi\": {\n      \"command\": \"uv\",\n      \"args\": [\"--directory\", \"/path/to/mcp-fredapi\", \"run\", \"--with\", \"mcp\", \"--with\", \"httpx\", \"mcp\", \"run\", \"server.py\"]\n    }\n  }\n}\n```\n\nReplace `/path/to/mcp-fredapi` with the actual path to the repository on your system. For example:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-fredapi\": {\n      \"command\": \"uv\",\n      \"args\": [\"--directory\", \"/path/to/mcp-fredapi\", \"run\", \"--with\", \"mcp\", \"--with\", \"httpx\", \"mcp\", \"run\", \"server.py\"]\n    }\n  }\n}\n```\n\nNote: On Windows, you can use either forward slashes `/` or double backslashes `\\\\` in the path.\n\n## Available Tools\n\n### get_fred_series_observations\n\nRetrieves economic time series observations from FRED.\n\nWhen using Claude in Cursor, you can access this tool directly with:\n\n```\n@mcp-fredapi:get_fred_series_observations\n```\n\n## Parameters\n\nThe `get_fred_series_observations` tool accepts the following parameters. For complete technical details about each parameter, please refer to the [official FRED API documentation](https://fred.stlouisfed.org/docs/api/fred/series_observations.html).\n\n| Parameter | Type | Description | Allowed Values | Default Value | Status |\n|-----------|------|-------------|---------------|---------------|--------|\n| series_id | str | The ID of the economic series | - | (Required) | ✅ Works |\n| sort_order | str | Sort order of observations | 'asc', 'desc' | 'asc' | ✅ Works |\n| units | str | Data value transformation | 'lin', 'chg', 'ch1', 'pch', 'pc1', 'pca', 'cch', 'cca', 'log' | 'lin' | ✅ Works |\n| frequency | str | Frequency of observations | 'd', 'w', 'bw', 'm', 'q', 'sa', 'a', 'wef', 'weth', 'wew', 'wetu', 'wem', 'wesu', 'wesa', 'bwew', 'bwem' | None | ✅ Works |\n| aggregation_method | str | Aggregation method for frequency | 'avg', 'sum', 'eop' | 'avg' | ✅ Works |\n| output_type | int | Output type of observations | 1, 2, 3, 4 | 1 | ✅ Works |\n| realtime_start | str | Start of real-time period (YYYY-MM-DD) | - | None | ❌ Not working |\n| realtime_end | str | End of real-time period (YYYY-MM-DD) | - | None | ❌ Not working |\n| limit | int/str | Maximum number of observations to return | Between 1 and 100000 | 10 | ❌ Not working |\n| offset | int/str | Number of observations to skip from the beginning | - | 0 | ❌ Not working |\n| observation_start | str | Start date of observations (YYYY-MM-DD) | - | None | ❌ Not working |\n| observation_end | str | End date of observations (YYYY-MM-DD) | - | None | ❌ Not working |\n| vintage_dates | str | Comma-separated list of vintage dates | - | None | ❌ Not working |\n\n\u003e [!WARNING]\n\u003e \n\u003e Due to current limitations with the MCP implementation, only certain parameters are working properly:\n\u003e - ✅ **Working parameters**: `series_id`, `sort_order`, `units`, `frequency` , aggregation_method`, and `output_type`.\n\u003e - ❌ **Non-working parameters**: `realtime_start`, `realtime_end`, `limit`, `offset`, `observation_start`, `observation_end`, and `vintage_dates`.\n\u003e\n\u003e For best results, stick with the working parameters in your queries. Future updates may resolve these limitations.\n\n## Examples\n\n### Getting US GDP Data\n\nWhen using Claude in Cursor, you can ask for GDP data like this:\n\n```\nCan you get the latest GDP data from FRED?\n\n@mcp-fredapi:get_fred_series_observations\n{\n  \"series_id\": \"GDP\"\n}\n```\n\n### Getting GDP Data in Descending Order\n\n```\nCan you get the GDP data in descending order (newest first)?\n\n@mcp-fredapi:get_fred_series_observations\n{\n  \"series_id\": \"GDP\",\n  \"sort_order\": \"desc\"\n}\n```\n\n### Getting Annual GDP Data\n\n```\nCan you get annual GDP data?\n\n@mcp-fredapi:get_fred_series_observations\n{\n  \"series_id\": \"GDP\",\n  \"frequency\": \"a\"\n}\n```\n\n### Getting Inflation Rate\n\nTo get consumer price index data with percent change:\n\n```\nWhat's the recent inflation rate in the US?\n\n@mcp-fredapi:get_fred_series_observations\n{\n  \"series_id\": \"CPIAUCSL\",\n  \"units\": \"pch\",\n  \"frequency\": \"m\"\n}\n```\n\n### Different Output Format\n\n```\nShow me GDP data in a different format.\n\n@mcp-fredapi:get_fred_series_observations\n{\n  \"series_id\": \"GDP\",\n  \"output_type\": 2\n}\n```\n\n## Contributing\n\nContributions are welcome. Please follow these steps:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Commit your changes (`git commit -m 'Add an amazing feature'`)\n5. Push to the branch (`git push origin feature/amazing-feature`)\n6. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## References\n\n- [FRED API Documentation - Series Observations](https://fred.stlouisfed.org/docs/api/fred/series_observations.html) - Official documentation for the FRED API endpoint used in this project.\n- [FRED API](https://fred.stlouisfed.org/docs/api/api_key.html) - Information on obtaining an API key and general API documentation.\n- [Model Context Protocol](https://modelcontextprotocol.github.io/) - Documentation for the Model Context Protocol.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaldekoa%2Fmcp-fredapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaldekoa%2Fmcp-fredapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaldekoa%2Fmcp-fredapi/lists"}