Skip to content
Back to search

fred-mcp-server

Open-source FRED MCP Server (Federal Reserve Economic Data)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/stefanoamorelli--fred-mcp-server/badge.svg)](/listings/stefanoamorelli--fred-mcp-server)

HTML

<a href="/listings/stefanoamorelli--fred-mcp-server"><img src="/api/listings/stefanoamorelli--fred-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Manual Installation

1. Clone the repository: ```bash git clone https://github.com/stefanoamorelli/fred-mcp-server.git cd fred-mcp-server ``` 2. Install dependencies: ```bash pnpm install ``` 3. Build the project: ```bash pnpm build ```

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 280 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Federal Reserve Economic Data MCP Server
  2. [![npm version](https://img.shields.io/npm/v/fred-mcp-server.svg)](https://www.npmjs.com/package/fred-mcp-server)
  3. [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.14536707.svg)](https://doi.org/10.5281/zenodo.14536707)
  4. [![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
  5. [![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)
  6. [![Documentation](https://img.shields.io/badge/docs-fred--mcp--server.amorelli.tech-blue)](https://fred-mcp-server.amorelli.tech)
  7. > [!IMPORTANT]
  8. > *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.
  9. A 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.
  10. https://github.com/user-attachments/assets/66c7f3ad-7b0e-4930-b1c5-a675a7eb1e09
  11. > [!TIP]
  12. > 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:
  13. **APA Format:**
  14. ```
  15. 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.14536707
  16. ```
  17. **BibTeX:**
  18. ```bibtex
  19. @software{amorelli_2025_14536707,
  20. author = {Amorelli, Stefano},
  21. title = {{Federal Reserve Economic Data MCP (Model Context
  22. Protocol) Server}},
  23. month = jan,
  24. year = 2025,
  25. publisher = {Zenodo},
  26. version = {1.0.2},
  27. doi = {10.5281/zenodo.14536707},
  28. url = {https://doi.org/10.5281/zenodo.14536707}
  29. }
  30. ```
  31. ## Installation
  32. ### Manual Installation
  33. 1. Clone the repository:
  34. ```bash
  35. git clone https://github.com/stefanoamorelli/fred-mcp-server.git
  36. cd fred-mcp-server
  37. ```
  38. 2. Install dependencies:
  39. ```bash
  40. pnpm install
  41. ```
  42. 3. Build the project:
  43. ```bash
  44. pnpm build
  45. ```
  46. ## Configuration
  47. This server requires a FRED® API key. You can obtain one from the [FRED® website](https://fred.stlouisfed.org/docs/api/api_key.html).
  48. Install the server, for example, on [Claude Desktop](https://claude.ai/download), modify the `claude_desktop_config.json` file and add the following configuration:
  49. ```json
  50. {
  51. "mcpServers": {
  52. "FRED MCP Server": {
  53. "command": "/usr/bin/node",
  54. "args": [
  55. "<PATH_TO_YOUR_CLONED_REPO>/fred-mcp-server/build/index.js"
  56. ],
  57. "env": {
  58. "FRED_API_KEY": "<YOUR_API_KEY>"
  59. }
  60. }
  61. }
  62. }
  63. ```
  64. ### Using Docker
  65. You can also run the FRED MCP Server using Docker. Add this configuration to your `claude_desktop_config.json`:
  66. ```json
  67. {
  68. "mcpServers": {
  69. "fred-mcp": {
  70. "command": "docker",
  71. "args": [
  72. "run",
  73. "-i",
  74. "--rm",
  75. "-e",
  76. "FRED_API_KEY=<your-key-here>",
  77. "stefanoamorelli/fred-mcp-server:latest"
  78. ],
  79. "env": {}
  80. }
  81. }
  82. }
  83. ```
  84. Replace `<your-key-here>` with your actual FRED API key.
  85. ### Using Streamable HTTP Transport
  86. For network deployments, you can run the server with Streamable HTTP transport instead of stdio:
  87. ```bash
  88. # Using CLI flag
  89. node build/index.js --http
  90. # Or using environment variable
  91. TRANSPORT=http node build/index.js
  92. # Custom port (default is 3000)
  93. PORT=8080 node build/index.js --http
  94. ```
  95. The server will be available at `http://localhost:3000/mcp` (or your custom port).
  96. **Example client request:**
  97. ```bash
  98. # Initialize session
  99. curl -X POST http://localhost:3000/mcp \
  100. -H "Content-Type: application/json" \
  101. -H "Accept: application/json, text/event-stream" \
  102. -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}'
  103. # Use the mcp-session-id from the response header for subsequent requests
  104. curl -X POST http://localhost:3000/mcp \
  105. -H "Content-Type: application/json" \
  106. -H "Accept: application/json, text/event-stream" \
  107. -H "mcp-session-id: <session-id-from-init>" \
  108. -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
  109. ```
  110. A `GET /healthz` endpoint reports active sessions, cache statistics, and uptime for load balancers and orchestrators.
  111. ### Configuration
  112. All settings are environment variables with sensible defaults:
  113. | Variable | Default | Description |
  114. |----------|---------|-------------|
  115. | `FRED_API_KEY` | (required) | Your FRED API key |
  116. | `FRED_API_TIMEOUT_MS` | `30000` | Per-request timeout against the FRED API |
  117. | `FRED_API_MAX_RETRIES` | `3` | Retries for 429/5xx/network failures (exponential backoff with jitter, honors `Retry-After`) |
  118. | `FRED_API_RETRY_BASE_DELAY_MS` | `500` | Base delay for retry backoff |
  119. | `FRED_RATE_LIMIT_PER_MINUTE` | `120` | Client-side token bucket matching FRED's per-key quota |
  120. | `FRED_CACHE_TTL_MS` | `60000` | TTL for cached API responses (`0` disables caching) |
  121. | `FRED_CACHE_MAX_ENTRIES` | `500` | LRU cache capacity |
  122. | `TRANSPORT` | `stdio` | Set to `http` for Streamable HTTP transport |
  123. | `HOST` | (all interfaces) | HTTP bind address |
  124. | `PORT` | `3000` | HTTP port |
  125. | `MCP_MAX_SESSIONS` | `100` | Maximum concurrent MCP sessions (new sessions get `503` beyond this) |
  126. | `MCP_SESSION_TTL_MS` | `1800000` | Idle time before a session is reaped |
  127. | `MCP_SESSION_SWEEP_INTERVAL_MS` | `60000` | How often the idle-session reaper runs |
  128. | `MCP_BODY_LIMIT` | `1mb` | Maximum accepted JSON body size |
  129. | `LOG_LEVEL` | `info` | `error`, `warn`, `info`, or `debug` (logs go to stderr) |
  130. Identical concurrent requests are coalesced into a single upstream call, and successful responses are cached, so multiple sessions share one rate-limit budget efficiently.
  131. ## Available Tools
  132. This MCP server provides three comprehensive tools to access all 800,000+ FRED® economic data series:
  133. ### `fred_browse`
  134. **Description**: Browse FRED's complete catalog through categories, releases, or sources.
  135. **Parameters**:
  136. * `browse_type` (required): Type of browsing - "categories", "releases", "sources", "category_series", "release_series"
  137. * `category_id` (optional): Category ID for browsing subcategories or series within a category
  138. * `release_id` (optional): Release ID for browsing series within a release
  139. * `limit` (optional): Maximum number of results (default: 50)
  140. * `offset` (optional): Number of results to skip for pagination
  141. * `order_by` (optional): Field to order results by
  142. * `sort_order` (optional): "asc" or "desc"
  143. ### `fred_search`
  144. **Description**: Search for FRED economic data series by keywords, tags, or filters.
  145. **Parameters**:
  146. * `search_text` (optional): Text to search for in series titles and descriptions
  147. * `search_type` (optional): "full_text" or "series_id"
  148. * `tag_names` (optional): Comma-separated list of tag names to filter by
  149. * `exclude_tag_names` (optional): Comma-separated list of tag names to exclude
  150. * `limit` (optional): Maximum number of results (default: 25)
  151. * `offset` (optional): Number of results to skip for pagination
  152. * `order_by` (optional): Field to order by (e.g., "popularity", "last_updated")
  153. * `sort_order` (optional): "asc" or "desc"
  154. * `filter_variable` (optional): Filter by "frequency", "units", or "seasonal_adjustment"
  155. * `filter_value` (optional): Value to filter the variable by
  156. ### `fred_get_series`
  157. **Description**: Retrieve data for any FRED series by its ID with support for transformations and date ranges.
  158. **Parameters**:
  159. * `series_id` (required): The FRED series ID (e.g., "GDP", "UNRATE", "CPIAUCSL")
  160. * `observation_start` (optional): Start date in YYYY-MM-DD format
  161. * `observation_end` (optional): End date in YYYY-MM-DD format
  162. * `limit` (optional): Maximum number of observations
  163. * `offset` (optional): Number of observations to skip
  164. * `sort_order` (optional): "asc" or "desc"
  165. * `units` (optional): Data transformation:
  166. - "lin" (levels/no transformation)
  167. - "chg" (change from previous period)
  168. - "ch1" (change from year ago)
  169. - "pch" (percent change)
  170. - "pc1" (percent change from year ago)
  171. - "pca" (compounded annual rate of change)
  172. - "cch" (continuously compounded rate of change)
  173. - "log" (natural log)
  174. * `frequency` (optional): Frequency aggregation ("d", "w", "m", "q", "a")
  175. * `aggregation_method` (optional): "avg" (average), "sum", or "eop" (end of period)
  176. ## Example Usage
  177. With these three tools, you can:
  178. - Browse all economic categories and discover available data
  179. - Search for specific indicators by keywords or tags
  180. - Retrieve any of the 800,000+ series with custom transformations
  181. - Access real-time economic data including GDP, unemployment, inflation, interest rates, and more
  182. ## Social Media Shoutouts 📣
  183. > [!NOTE]
  184. > 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!
  185. We're grateful for the community support! Here are some mentions from amazing people:
  186. <details open>
  187. <summary><b>Scott G</b> - "One of my breakthrough moments for 'getting' what is possible with Claude was this fred-mcp-server project..."</summary>
  188. <br>
  189. <a href="https://www.linkedin.com/posts/sgoley_as-many-of-us-continue-to-use-llms-more-and-activity-7372401049669885952-ha6M">
  190. <img src="assets/social/linkedin-sgoley.jpg" alt="LinkedIn post by Scott G - Fintech & Data Analytics Professional" width="600">
  191. </a>
  192. <br>
  193. <i>Scott G - Fintech & Data Analytics Professional</i> | <a href="https://www.linkedin.com/in/sgoley/">LinkedIn Profile</a>
  194. </details>
  195. <details open>
  196. <summary><b>John Shelburne</b> - "The FRED MCP Server is a game-changer for financial analysis..."</summary>
  197. <br>
  198. <a href="https://www.linkedin.com/posts/shelburne_ai-finance-innovation-activity-7341141860880478210-JQe4">
  199. <img src="assets/social/linkedin-john-shelburne.jpg" alt="LinkedIn post by John Shelburne" width="600">
  200. </a>
  201. <br>
  202. <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>
  203. </details>
  204. <!-- Add more social media posts here using the format above -->
  205. ## Testing
  206. See [TESTING.md](./TESTING.md) for more details.
  207. ```bash
  208. # Run all tests
  209. pnpm test
  210. # Run specific tests
  211. pnpm test:registry
  212. ```
  213. ## License ⚖️
  214. This open-source project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). This means:
  215. - You can use, modify, and distribute this software
  216. - If you modify and distribute it, you must release your changes under AGPL-3.0
  217. - If you run a modified version on a server, you must provide the source code to users
  218. - See the [LICENSE](LICENSE) file for full details
  219. For commercial licensing options or other licensing inquiries, please contact [stefano@amorelli.tech](mailto:stefano@amorelli.tech).
  220. © 2025 [Stefano Amorelli](https://amorelli.tech)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.