Federal Reserve Economic Data

Acesse conjuntos de dados financeiros da API Federal Reserve Economic Data (FRED).

GitHub
122
Experimente este MCPPatrocinado

Documentação

Servidor MCP de Dados Econômicos do Federal Reserve

npm version DOI License: AGPL v3 Tests Documentation

[!IMPORTANT] Aviso: Este projeto de código aberto não é afiliado, patrocinado ou endossado pelo Federal Reserve ou pelo Federal Reserve Bank of St. Louis. "FRED" é uma marca registrada do Federal Reserve Bank of St. Louis, usada aqui apenas para fins descritivos.

Um servidor Model Context Protocol (MCP) que fornece acesso universal a todas as mais de 800.000 séries temporais de Dados Econômicos do Federal Reserve (FRED®) por meio de três ferramentas poderosas.

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

[!TIP] Se você usar este projeto em sua pesquisa ou trabalho, cite-o usando o arquivo CITATION.cff ou use a seguinte citação:

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

Instalação

Instalação Manual

  1. Clone o repositório: 
    git clone https://github.com/stefanoamorelli/fred-mcp-server.git
cd fred-mcp-server
  2. Instale as dependências: 
    pnpm install
  3. Compile o projeto: 
    pnpm build

Configuração

Este servidor requer uma chave de API FRED®. Você pode obter uma no site do FRED®.

Instale o servidor, por exemplo, no Claude Desktop, modifique o arquivo claude_desktop_config.json e adicione a seguinte configuração:

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

Você também pode executar o Servidor MCP FRED usando Docker. Adicione esta configuração ao seu 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": {}
    }
  }
}

Substitua <your-key-here> pela sua chave real da API FRED.

Usando Transporte HTTP Streamable

Para implantações em rede, você pode executar o servidor com transporte HTTP Streamable em vez 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

O servidor estará disponível em http://localhost:3000/mcp (ou na sua porta personalizada).

Exemplo de solicitação do 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"}'

Um endpoint GET /healthz relata sessões ativas, estatísticas de cache e tempo de atividade para balanceadores de carga e orquestradores.

Configuração

Todas as configurações são variáveis de ambiente com padrões sensatos:

VariávelPadrãoDescrição
FRED_API_KEY(obrigatório)Sua chave da API FRED
FRED_API_TIMEOUT_MS30000Tempo limite por solicitação contra a API FRED
FRED_API_MAX_RETRIES3Tentativas para falhas 429/5xx/rede (backoff exponencial com jitter, respeita Retry-After)
FRED_API_RETRY_BASE_DELAY_MS500Atraso base para backoff de tentativas
FRED_RATE_LIMIT_PER_MINUTE120Token bucket no lado do cliente correspondente à cota por chave do FRED
FRED_CACHE_TTL_MS60000TTL para respostas de API em cache (0 desativa o cache)
FRED_CACHE_MAX_ENTRIES500Capacidade do cache LRU
TRANSPORTstdioDefina como http para transporte HTTP Streamable
HOST(todas as interfaces)Endereço de bind HTTP
PORT3000Porta HTTP
MCP_MAX_SESSIONS100Máximo de sessões MCP simultâneas (novas sessões recebem 503 além disso)
MCP_SESSION_TTL_MS1800000Tempo ocioso antes que uma sessão seja encerrada
MCP_SESSION_SWEEP_INTERVAL_MS60000Com que frequência o coletor de sessões ociosas é executado
MCP_BODY_LIMIT1mbTamanho máximo aceito do corpo JSON
LOG_LEVELinfoerror, warn, info ou debug (os logs vão para stderr)

Solicitações concorrentes idênticas são combinadas em uma única chamada upstream, e respostas bem-sucedidas são armazenadas em cache, para que várias sessões compartilhem um orçamento de limite de taxa com eficiência.

Ferramentas Disponíveis

Este servidor MCP fornece três ferramentas abrangentes para acessar todas as mais de 800.000 séries de dados econômicos FRED®:

fred_browse

Descrição: Navegue pelo catálogo completo do FRED por categorias, lançamentos ou fontes.

Parâmetros:

  • browse_type (obrigatório): Tipo de navegação - "categories", "releases", "sources", "category_series", "release_series"
  • category_id (opcional): ID da categoria para navegar por subcategorias ou séries dentro de uma categoria
  • release_id (opcional): ID do lançamento para navegar por séries dentro de um lançamento
  • limit (opcional): Número máximo de resultados (padrão: 50)
  • offset (opcional): Número de resultados a pular para paginação
  • order_by (opcional): Campo para ordenar os resultados
  • sort_order (opcional): "asc" ou "desc"

fred_search

Descrição: Pesquise séries de dados econômicos FRED por palavras-chave, tags ou filtros.

Parâmetros:

  • search_text (opcional): Texto para pesquisar em títulos e descrições de séries
  • search_type (opcional): "full_text" ou "series_id"
  • tag_names (opcional): Lista separada por vírgulas de nomes de tags para filtrar
  • exclude_tag_names (opcional): Lista separada por vírgulas de nomes de tags para excluir
  • limit (opcional): Número máximo de resultados (padrão: 25)
  • offset (opcional): Número de resultados a pular para paginação
  • order_by (opcional): Campo para ordenar (ex.: "popularity", "last_updated")
  • sort_order (opcional): "asc" ou "desc"
  • filter_variable (opcional): Filtrar por "frequency", "units" ou "seasonal_adjustment"
  • filter_value (opcional): Valor para filtrar a variável

fred_get_series

Descrição: Recupere dados de qualquer série FRED pelo seu ID com suporte para transformações e intervalos de datas.

Parâmetros:

  • series_id (obrigatório): O ID da série FRED (ex.: "GDP", "UNRATE", "CPIAUCSL")
  • observation_start (opcional): Data de início no formato AAAA-MM-DD
  • observation_end (opcional): Data de término no formato AAAA-MM-DD
  • limit (opcional): Número máximo de observações
  • offset (opcional): Número de observações a pular
  • sort_order (opcional): "asc" ou "desc"
  • units (opcional): Transformação de dados:
    • "lin" (níveis/sem transformação)
    • "chg" (mudança em relação ao período anterior)
    • "ch1" (mudança em relação ao ano anterior)
    • "pch" (mudança percentual)
    • "pc1" (mudança percentual em relação ao ano anterior)
    • "pca" (taxa anual composta de mudança)
    • "cch" (taxa de mudança continuamente composta)
    • "log" (logaritmo natural)
  • frequency (opcional): Agregação de frequência ("d", "w", "m", "q", "a")
  • aggregation_method (opcional): "avg" (média), "sum" ou "eop" (fim do período)

Exemplo de Uso

Com essas três ferramentas, você pode:

  • Navegar por todas as categorias econômicas e descobrir dados disponíveis
  • Pesquisar indicadores específicos por palavras-chave ou tags
  • Recuperar qualquer uma das mais de 800.000 séries com transformações personalizadas
  • Acessar dados econômicos em tempo real, incluindo PIB, desemprego, inflação, taxas de juros e muito mais

Menções nas Redes Sociais 📣

[!NOTE] Quer ser destaque? Marque Stefano Amorelli no LinkedIn ou @stefanoamorelli no X em sua publicação sobre o uso do Servidor MCP FRED, ou envie um PR para adicionar sua menção!

Somos gratos pelo apoio da comunidade! Aqui estão algumas menções de pessoas incríveis:

Scott G - "Um dos meus momentos de avanço para 'entender' o que é possível com Claude foi este projeto fred-mcp-server..."
LinkedIn post by Scott G - Fintech & Data Analytics Professional
Scott G - Profissional de Fintech e Análise de Dados | Perfil no LinkedIn
John Shelburne - "O Servidor MCP FRED é um divisor de águas para análise financeira..."
LinkedIn post by John Shelburne
John Shelburne - Líder em Fintech de Renda Fixa com mais de 20 Anos de Experiência | Especialista em Machine Learning e Computação em Nuvem | Perfil no LinkedIn

Testes

Consulte TESTING.md para mais detalhes.

# Run all tests
pnpm test

# Run specific tests
pnpm test:registry

Licença ⚖️

Este projeto de código aberto é licenciado sob a GNU Affero General Public License v3.0 (AGPL-3.0). Isso significa:

  • Você pode usar, modificar e distribuir este software
  • Se você modificar e distribuir, deve divulgar suas alterações sob AGPL-3.0
  • Se você executar uma versão modificada em um servidor, deve fornecer o código-fonte aos usuários
  • Consulte o arquivo LICENSE para detalhes completos

Para opções de licenciamento comercial ou outras consultas de licenciamento, entre em contato com stefano@amorelli.tech.

© 2025 Stefano Amorelli