Federal Reserve Economic Data

Accede a conjuntos de datos financieros desde la API de Federal Reserve Economic Data (FRED).

Documentación

Servidor MCP de Datos Económicos de la Reserva Federal

[!IMPORTANT] Aviso legal: Este proyecto de código abierto no está afiliado, patrocinado ni respaldado por la Reserva Federal ni por el Banco de la Reserva Federal de San Luis. "FRED" es una marca registrada del Banco de la Reserva Federal de San Luis, utilizada aquí únicamente con fines descriptivos.

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona acceso universal a las más de 800,000 series de tiempo de Datos Económicos de la Reserva Federal (FRED®) a través de tres potentes herramientas.

https://github.com/user-attachments/assets/66c7f3ad-7b0e-4930-b1c5-a675a7eb1e09

[!TIP] Si utiliza este proyecto en su investigación o trabajo, por favor cítelo utilizando el archivo CITATION.cff, o use la siguiente cita:

Formato APA:

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

BibTeX:

@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}
}

Instalación

Instalación Manual

Clone el repositorio:

git clone https://github.com/stefanoamorelli/fred-mcp-server.git
cd fred-mcp-server

Instale las dependencias:
```
pnpm install
```
Compile el proyecto:
```
pnpm build
```

Configuración

Este servidor requiere una clave API de FRED®. Puede obtener una en el sitio web de FRED®.

Instale el servidor, por ejemplo, en Claude Desktop, modifique el archivo claude_desktop_config.json y agregue la siguiente configuración:

{
  "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>"
      }
    }
  }
}

Usando Docker

También puede ejecutar el Servidor MCP de FRED usando Docker. Agregue esta configuración a su 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": {}
    }
  }
}

Reemplace <your-key-here> con su clave API real de FRED.

Usando Transporte HTTP Streamable

Para implementaciones en red, puede ejecutar el servidor con transporte HTTP Streamable en lugar de 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 --http

El servidor estará disponible en http://localhost:3000/mcp (o su puerto personalizado).

Ejemplo de solicitud de cliente:

# 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"}'

Un endpoint GET /healthz reporta sesiones activas, estadísticas de caché y tiempo de actividad para balanceadores de carga y orquestadores.

Configuración

Todas las configuraciones son variables de entorno con valores predeterminados sensatos:

Variable	Predeterminado	Descripción
`FRED_API_KEY`	(requerido)	Su clave API de FRED
`FRED_API_TIMEOUT_MS`	`30000`	Tiempo de espera por solicitud contra la API de FRED
`FRED_API_MAX_RETRIES`	`3`	Reintentos para fallos 429/5xx/red (retroceso exponencial con fluctuación, respeta `Retry-After`)
`FRED_API_RETRY_BASE_DELAY_MS`	`500`	Retraso base para el retroceso de reintentos
`FRED_RATE_LIMIT_PER_MINUTE`	`120`	Cubo de tokens del lado del cliente que coincide con la cuota por clave de FRED
`FRED_CACHE_TTL_MS`	`60000`	TTL para respuestas de API en caché (`0` desactiva el caché)
`FRED_CACHE_MAX_ENTRIES`	`500`	Capacidad del caché LRU
`TRANSPORT`	`stdio`	Establezca en `http` para transporte HTTP Streamable
`HOST`	(todas las interfaces)	Dirección de enlace HTTP
`PORT`	`3000`	Puerto HTTP
`MCP_MAX_SESSIONS`	`100`	Máximo de sesiones MCP concurrentes (las nuevas sesiones reciben `503` más allá de esto)
`MCP_SESSION_TTL_MS`	`1800000`	Tiempo de inactividad antes de que una sesión sea eliminada
`MCP_SESSION_SWEEP_INTERVAL_MS`	`60000`	Con qué frecuencia se ejecuta el eliminador de sesiones inactivas
`MCP_BODY_LIMIT`	`1mb`	Tamaño máximo aceptado del cuerpo JSON
`LOG_LEVEL`	`info`	`error`, `warn`, `info` o `debug` (los registros van a stderr)

Las solicitudes concurrentes idénticas se combinan en una sola llamada ascendente, y las respuestas exitosas se almacenan en caché, por lo que múltiples sesiones comparten un presupuesto de límite de tasa de manera eficiente.

Herramientas Disponibles

Este servidor MCP proporciona tres herramientas integrales para acceder a las más de 800,000 series de datos económicos de FRED®:

`fred_browse`

Descripción: Explore el catálogo completo de FRED a través de categorías, publicaciones o fuentes.

Parámetros:

browse_type (requerido): Tipo de exploración - "categories", "releases", "sources", "category_series", "release_series"
category_id (opcional): ID de categoría para explorar subcategorías o series dentro de una categoría
release_id (opcional): ID de publicación para explorar series dentro de una publicación
limit (opcional): Número máximo de resultados (predeterminado: 50)
offset (opcional): Número de resultados a omitir para paginación
order_by (opcional): Campo por el cual ordenar los resultados
sort_order (opcional): "asc" o "desc"

`fred_search`

Descripción: Busque series de datos económicos de FRED por palabras clave, etiquetas o filtros.

Parámetros:

search_text (opcional): Texto para buscar en títulos y descripciones de series
search_type (opcional): "full_text" o "series_id"
tag_names (opcional): Lista separada por comas de nombres de etiquetas para filtrar
exclude_tag_names (opcional): Lista separada por comas de nombres de etiquetas para excluir
limit (opcional): Número máximo de resultados (predeterminado: 25)
offset (opcional): Número de resultados a omitir para paginación
order_by (opcional): Campo por el cual ordenar (por ejemplo, "popularity", "last_updated")
sort_order (opcional): "asc" o "desc"
filter_variable (opcional): Filtrar por "frequency", "units" o "seasonal_adjustment"
filter_value (opcional): Valor para filtrar la variable

`fred_get_series`

Descripción: Recupere datos de cualquier serie de FRED por su ID con soporte para transformaciones y rangos de fechas.

Parámetros:

series_id (requerido): El ID de la serie de FRED (por ejemplo, "GDP", "UNRATE", "CPIAUCSL")
observation_start (opcional): Fecha de inicio en formato AAAA-MM-DD
observation_end (opcional): Fecha de fin en formato AAAA-MM-DD
limit (opcional): Número máximo de observaciones
offset (opcional): Número de observaciones a omitir
sort_order (opcional): "asc" o "desc"
units (opcional): Transformación de datos:
- "lin" (niveles/sin transformación)
- "chg" (cambio respecto al período anterior)
- "ch1" (cambio respecto al año anterior)
- "pch" (cambio porcentual)
- "pc1" (cambio porcentual respecto al año anterior)
- "pca" (tasa de cambio anual compuesta)
- "cch" (tasa de cambio compuesta continuamente)
- "log" (logaritmo natural)
frequency (opcional): Agregación de frecuencia ("d", "w", "m", "q", "a")
aggregation_method (opcional): "avg" (promedio), "sum" o "eop" (fin de período)

Ejemplo de Uso

Con estas tres herramientas, puede:

Explorar todas las categorías económicas y descubrir datos disponibles
Buscar indicadores específicos por palabras clave o etiquetas
Recuperar cualquiera de las más de 800,000 series con transformaciones personalizadas
Acceder a datos económicos en tiempo real, incluyendo PIB, desempleo, inflación, tasas de interés y más

Menciones en Redes Sociales 📣

[!NOTE] ¿Quiere aparecer? Etiquete a Stefano Amorelli en LinkedIn o @stefanoamorelli en X en su publicación sobre el uso del Servidor MCP de FRED, o envíe un PR para agregar su mención.

¡Agradecemos el apoyo de la comunidad! Aquí hay algunas menciones de personas increíbles:

Scott G - "Uno de mis momentos de revelación para 'entender' lo que es posible con Claude fue este proyecto fred-mcp-server..."

LinkedIn post by Scott G - Fintech & Data Analytics Professional

Scott G - Profesional de Fintech y Análisis de Datos | Perfil de LinkedIn

John Shelburne - "El Servidor MCP de FRED es un cambio de juego para el análisis financiero..."

John Shelburne - Líder de Fintech de Renta Fija con más de 20 años de experiencia | Especialista en Aprendizaje Automático y Computación en la Nube | Perfil de LinkedIn

Pruebas

Consulte TESTING.md para más detalles.

# Run all tests
pnpm test

# Run specific tests
pnpm test:registry

Licencia ⚖️

Este proyecto de código abierto está licenciado bajo la Licencia Pública General Affero de GNU v3.0 (AGPL-3.0). Esto significa:

Puede usar, modificar y distribuir este software
Si lo modifica y distribuye, debe publicar sus cambios bajo AGPL-3.0
Si ejecuta una versión modificada en un servidor, debe proporcionar el código fuente a los usuarios
Consulte el archivo LICENSE para más detalles

Para opciones de licencia comercial u otras consultas de licenciamiento, contacte a stefano@amorelli.tech.