EODHD MCP Server

Model Context Protocol (MCP) server for EOD Historical Data APIs.

The current server exposes 75 read-only MCP tools across three transports:

• streamable-http via server.py on /mcp by default
• sse
• stdio

It also ships bundled MCP prompts and documentation resources.

Coverage

Core datasets

• End-of-day, intraday, and US tick data
• Live quotes and US Live v2 extended quotes
• Fundamentals, earnings, and financial statements
• Company news, sentiment, and news word weights
• Screeners, search, and technical indicators
• Corporate actions: IPOs, splits, dividends, symbol changes
• Macro indicators, economic events, exchanges, and listings
• CBOE index tools
• Treasury bill, yield, real yield, and long-term rates

Marketplace and partner datasets

• US options: contracts, EOD, and underlyings
• illio: performance, risk, and market insights
• Praams: risk scoring, bonds, bank statements, reports, screeners
• Investverte ESG: companies, countries, and sectors
• TradingHours market lookup, market details, and status

Current Behavior

• All tools are read-only and register through app/tools/__init__.py.
• All HTTP requests go through the shared async client in app/api_client.py.
• Upstream API errors are preserved as MCP ToolErrors with status code and upstream details where available.
• API tokens are injected into EODHD requests as api_token=... query parameters.
• Optional retry support is controlled by EODHD_RETRY_ENABLED or per-call settings in code.

Requirements

• Python 3.10+
• A valid EODHD API key
• An MCP-compatible client such as Claude Desktop, Claude Code, ChatGPT MCP/Connectors, or MCP Inspector

Installation

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

For development tooling:

pip install -e ".[dev]"

Create a .env file at the repository root:

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

Running the Server

Recommended entrypoint

server.py is the main maintained entrypoint.

Run HTTP (default):

python server.py

Run HTTP explicitly:

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

Run SSE:

python server.py --sse

Run stdio:

python server.py --stdio

Override the API key from the CLI:

python server.py --stdio --apikey YOUR_EODHD_API_KEY

Compatibility entrypoints

The repo still includes legacy compatibility entrypoints in entrypoints/:

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

These are still usable, but server.py is the primary runtime surface.

Authentication Model

For outgoing EODHD requests, the server ultimately sends the token as api_token in the query string.

For incoming HTTP MCP requests, the server can resolve the EODHD token from:

• Authorization: Bearer <token>
• X-API-Key: <token>
• query params: apikey, api_key, or token
• fallback server environment: EODHD_API_KEY

Many tools also expose an explicit api_token argument for per-call override.

Using with Claude Desktop

Packaged extension

The packaged MCP manifest uses the stdio entrypoint in manifest.json.

Source checkout example

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

Using with ChatGPT MCP / Connectors

For local HTTP testing, use:

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

If your MCP client supports headers, you can provide the EODHD token via Authorization: Bearer ... or X-API-Key: .... Otherwise, set EODHD_API_KEY on the server.

Development Commands

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

Manual End-to-End Clients

The repository includes manual MCP clients in tests/manual/.

Start the main server in one terminal:

python server.py

Then run the HTTP manual client:

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

For SSE:

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

For stdio:

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

Manual test catalogs are loaded from tests/manual/all_tests.py by default.

Docker

Run with Docker Compose:

docker compose up --build

The compose service starts python server.py and maps ${MCP_PORT_OUT} to ${MCP_PORT}.

Project Layout

• server.py — main entrypoint and transport selection
• app/api_client.py — shared async HTTP client, auth injection, rate limiting, retry logic
• app/response_formatter.py — MCP resource formatting and API error raising
• app/input_formatter.py — input sanitization and date coercion
• app/tools/ — MCP tool implementations
• app/prompts/ — bundled MCP prompts
• app/resources/ — bundled MCP resources and reference docs
• tests/auto/ — automated tests
• tests/manual/ — manual end-to-end MCP clients

Notes

• Some marketplace endpoints require specific EODHD subscription access.
• A valid API key can still receive upstream permission errors for tools or watchlists not included in the account plan.
• The server now preserves those upstream reasons in agent-visible tool errors instead of masking them behind generic failures.