EODHD MCP Server

Acesse dados globais do mercado financeiro por meio de 70+ ferramentas: preços de fechamento e intradiários, fundamentos, lucros e demonstrações financeiras, notícias e sentimento, filtros de ações, indicadores técnicos, macro e mais - em ações, ETFs, forex e cripto.

GitHub
20
Experimente este MCPPatrocinado

Documentação

EODHD logo

Servidor MCP EODHD

Servidor Model Context Protocol (MCP) para as APIs da EOD Historical Data.

O servidor atual expõe 88 ferramentas MCP em três transportes — 85 são somente leitura; as três ferramentas de relatórios Praams acionam a geração de relatórios no provedor e o envio por e-mail, portanto são anotadas como readOnlyHint=False:

  • streamable-http via server.py em /mcp por padrão
  • sse
  • stdio

Ele também inclui prompts MCP e recursos de documentação integrados.

Cobertura

Conjuntos de dados principais

  • Dados de fim de dia, intraday e ticks dos EUA
  • Cotações ao vivo e cotações estendidas US Live v2
  • Fundamentos, lucros e demonstrações financeiras
  • Notícias de empresas, sentimento e pesos de palavras em notícias
  • Screeners, busca e indicadores técnicos
  • Ações corporativas: IPOs, desdobramentos, dividendos, mudanças de símbolo
  • Indicadores macroeconômicos, eventos econômicos, bolsas e listagens
  • Ferramentas de índices CBOE
  • Títulos do Tesouro, rendimentos, rendimentos reais e taxas de longo prazo
  • Risco de crédito e soberano: prêmios de risco, ratings de crédito, spreads de CDS/inadimplência, rendimentos corporativos CMDI/HQM, agregados do mercado de CDS
  • Sanções / OFAC: entidades, embarcações, programas, fontes
  • Taxas de juros: taxas de referência (SOFR etc.), taxas de política do banco central, spreads de estresse de financiamento

Conjuntos de dados de marketplace e parceiros

  • Opções dos EUA: contratos, EOD e subjacentes
  • Praams: pontuação de risco, títulos, extratos bancários, relatórios, screeners
  • Investverte ESG: empresas, países e setores
  • Pesquisa de mercado TradingHours, detalhes de mercado e status

Comportamento Atual

  • Todas as ferramentas são somente leitura, exceto as três ferramentas de relatórios Praams; cada ferramenta é registrada por meio de app/tools/__init__.py.
  • Todas as solicitações HTTP passam pelo cliente assíncrono compartilhado em app/api_client.py.
  • Erros da API upstream são preservados como ToolErrors MCP com código de status e detalhes upstream quando disponíveis.
  • Tokens de API são injetados nas solicitações EODHD como parâmetros de consulta api_token=....
  • Suporte opcional a tentativas é controlado por EODHD_RETRY_ENABLED ou configurações por chamada no código.

Requisitos

  • Python 3.10+
  • Uma chave de API EODHD válida
  • Um cliente compatível com MCP, como Claude Desktop, Claude Code, ChatGPT MCP/Connectors ou MCP Inspector

Instalação

git clone https://github.com/EodHistoricalData/EODHD-MCP-Server.git
cd EODHD-MCP-Server
pip install -r requirements.txt

Para ferramentas de desenvolvimento:

pip install -e ".[dev]"

Crie um arquivo .env na raiz do repositório:

EODHD_API_KEY=YOUR_EODHD_API_KEY
MCP_HOST=127.0.0.1
MCP_PORT=8000
MCP_PATH=/mcp
LOG_LEVEL=INFO
# Optional:
EODHD_RETRY_ENABLED=false
# Deployment label added to the outbound User-Agent (e.g. v1 / v2):
EODHD_MCP_EDITION=
# Usage telemetry — both are required, and nothing is emitted unless both are set:
EODHD_MCP_TELEMETRY_URL=
EODHD_MCP_TELEMETRY_KEY=

Executando o Servidor

Ponto de entrada recomendado

server.py é o principal ponto de entrada mantido.

Execute HTTP (padrão):

python server.py

Execute HTTP explicitamente:

python server.py --http --host 127.0.0.1 --port 8000 --path /mcp

Execute SSE:

python server.py --sse

Execute stdio:

python server.py --stdio

Substitua a chave de API pela CLI:

python server.py --stdio --apikey YOUR_EODHD_API_KEY

Pontos de entrada de compatibilidade

O repositório ainda inclui pontos de entrada de compatibilidade legados em entrypoints/:

python -m entrypoints.server_http
python -m entrypoints.server_sse
python -m entrypoints.server_stdio --apikey YOUR_EODHD_API_KEY

Eles ainda são utilizáveis, mas server.py é a superfície de execução principal.

Modelo de Autenticação

Para solicitações EODHD de saída, o servidor envia o token como api_token na string de consulta.

Para solicitações HTTP MCP de entrada, o servidor pode resolver o token EODHD a partir de:

  • Authorization: Bearer <token>
  • X-API-Key: <token>
  • parâmetros de consulta: apikey, api_key ou token
  • ambiente do servidor de fallback: EODHD_API_KEY

Muitas ferramentas também expõem um argumento explícito api_token para substituição por chamada.

Usando com Claude Desktop

Extensão empacotada

O manifesto MCP empacotado usa o ponto de entrada stdio em manifest.json.

Exemplo de checkout do código-fonte

{
  "mcpServers": {
    "eodhd-mcp": {
      "command": "python3",
      "args": [
        "/absolute/path/to/EODHD-MCP-Server/server.py",
        "--stdio"
      ],
      "env": {
        "EODHD_API_KEY": "YOUR_EODHD_API_KEY"
      }
    }
  }
}

Usando com ChatGPT MCP / Connectors

Para testes HTTP locais, use:

  • URL: http://127.0.0.1:8000/mcp

Se o seu cliente MCP suportar cabeçalhos, você pode fornecer o token EODHD via Authorization: Bearer ... ou X-API-Key: .... Caso contrário, defina EODHD_API_KEY no servidor.

Comandos de Desenvolvimento

pytest tests/auto/ -v --tb=short
pytest tests/auto/ -v --cov=app --cov-report=term-missing
ruff check app/ server.py
ruff format --check app/ server.py
mypy app/ server.py --ignore-missing-imports --explicit-package-bases
bandit -r app/ -ll -ii -x app/resources/
semgrep scan --config p/python --config p/owasp-top-ten --config p/secrets --config p/jwt --error app/
python server.py
python server.py --stdio

Clientes Manuais de Ponta a Ponta

O repositório inclui clientes MCP manuais em tests/manual/.

Inicie o servidor principal em um terminal:

python server.py

Em seguida, execute o cliente manual HTTP:

python tests/manual/test_client_http.py --endpoint http://127.0.0.1:8000/mcp

Para SSE:

python server.py --sse
python tests/manual/test_client_sse.py --endpoint http://127.0.0.1:8000/sse

Para stdio:

python tests/manual/test_client_stdio.py --cmd "python server.py --stdio --apikey YOUR_EODHD_API_KEY"

Catálogos de teste manuais são carregados de tests/manual/all_tests.py por padrão.

Docker

Execute com Docker Compose:

docker compose up --build

O serviço do compose inicia python server.py e mapeia ${MCP_PORT_OUT} para ${MCP_PORT}.

Estrutura do Projeto

  • server.py — ponto de entrada principal e seleção de transporte
  • app/api_client.py — cliente HTTP assíncrono compartilhado, injeção de autenticação, limitação de taxa, lógica de tentativas
  • app/response_formatter.py — formatação de recursos MCP e geração de erros de API
  • app/input_formatter.py — sanitização de entrada e coerção de datas
  • app/tools/ — implementações de ferramentas MCP
  • app/prompts/ — prompts MCP integrados
  • app/resources/ — recursos MCP integrados e documentos de referência
  • tests/auto/ — testes automatizados
  • tests/manual/ — clientes MCP manuais de ponta a ponta

Notas

  • Alguns endpoints de marketplace exigem acesso específico à assinatura EODHD.
  • Uma chave de API válida ainda pode receber erros de permissão upstream para ferramentas ou watchlists não incluídos no plano da conta.
  • O servidor agora preserva esses motivos upstream em erros de ferramentas visíveis ao agente, em vez de mascará-los com falhas genéricas.

Política de Privacidade

Este conector é operado pela EOD Historical Data (Unicorn Data Services). Ele envia os parâmetros que você fornece (por exemplo, tickers, intervalos de datas e sua chave de API) para as APIs EODHD para atender a cada solicitação e retorna as respostas ao seu cliente MCP. Ele não coleta nem armazena conteúdo de conversa além do necessário para atender a uma solicitação.

Política de privacidade completa: https://eodhd.com/financial-apis/privacy-policy