EODHD-MCP-Server CLAUDE.md

EODHD MCP Server v1

MCP server exposing 88 EODHD financial data API tools via HTTP, SSE, and stdio transports.

Stack

Python 3.10+, FastMCP >=3.4, httpx (async HTTP), Ruff, MyPy, pytest, Bandit, Semgrep, pip-audit

Commands

# Tests
pytest tests/auto/ -v --tb=short
pytest tests/auto/ -v --cov=app --cov-report=term-missing

# Lint & format
ruff check app/ server.py
ruff format --check app/ server.py

# Type checking
mypy app/ server.py --ignore-missing-imports --explicit-package-bases

# Security
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/
pip-audit --ignore-vuln CVE-2026-4539

# Run server
python server.py
python server.py --stdio
python server.py --sse
python server.py --http --port 9000

Architecture

app/
  config.py           - env vars, API base URL
  api_client.py       - shared async httpx client, retry, rate-limit, auth injection
  input_formatter.py  - input sanitisation, date coercion, URL helpers
  response_formatter.py - MCP EmbeddedResource formatting and API error raising
  tools/              - 88 tool modules, each exports register(mcp)
    __init__.py       - ALL_TOOLS list, register_all(mcp), safe dynamic import
  prompts/            - example workflows
  resources/          - markdown reference docs exposed as MCP resources
server.py             - entry point, transport selection, argparse

Tool Categories

• MAIN_TOOLS - core EODHD endpoints
• MARKETPLACE_TOOLS - marketplace partner endpoints
• THIRD_PARTY_TOOLS - praams, investverte partner tools

Conventions

• Every tool file exports register(mcp: FastMCP).
• All tools are read-only (readOnlyHint=True) except the three Praams report tools, which generate a report and email it to the caller-supplied address (readOnlyHint=False).
• Sanitize inputs with helpers from app/input_formatter.py.
• Raise ToolError for user-facing failures.
• Route all HTTP traffic through make_request() in app/api_client.py.
• Return MCP resources via response_formatter helpers, not raw json.dumps.
• Preserve explicit upstream API errors; do not silently pass through {"error": ...} payloads as successful results.
• No cross-tool imports.
• No print() in app code; use logging.
• Use X | None instead of Optional[X].