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.