# EODHD MCP Server
Model Context Protocol (MCP) server for [EOD Historical Data](https://eodhd.com/) APIs.
The current server exposes **88 MCP tools** across three transports — 85 are read-only; the three
Praams report tools trigger provider-side report generation and email delivery, so they are annotated
`readOnlyHint=False`:
- `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
- Credit & sovereign risk: risk premiums, credit ratings, CDS/default spreads, corporate CMDI/HQM yields, CDS-market aggregates
- Sanctions / OFAC: entities, vessels, programs, sources
- Interest rates: reference rates (SOFR etc.), central-bank policy rates, funding-stress spreads
### Marketplace and partner datasets
- US options: contracts, EOD, and underlyings
- 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 except the three Praams report tools; every tool registers 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 `ToolError`s 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
```bash
git clone https://github.com/EodHistoricalData/EODHD-MCP-Server.git
cd EODHD-MCP-Server
pip install -r requirements.txt
```
For development tooling:
```bash
pip install -e ".[dev]"
```
Create a `.env` file at the repository root:
```env
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=
```
## Running the Server
### Recommended entrypoint
`server.py` is the main maintained entrypoint.
Run HTTP (default):
```bash
python server.py
```
Run HTTP explicitly:
```bash
python server.py --http --host 127.0.0.1 --port 8000 --path /mcp
```
Run SSE:
```bash
python server.py --sse
```
Run stdio:
```bash
python server.py --stdio
```
Override the API key from the CLI:
```bash
python server.py --stdio --apikey YOUR_EODHD_API_KEY
```
### Compatibility entrypoints
The repo still includes legacy compatibility entrypoints in `entrypoints/`:
```bash
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 `
- `X-API-Key: `
- 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
```json
{
"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
```bash
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:
```bash
python server.py
```
Then run the HTTP manual client:
```bash
python tests/manual/test_client_http.py --endpoint http://127.0.0.1:8000/mcp
```
For SSE:
```bash
python server.py --sse
python tests/manual/test_client_sse.py --endpoint http://127.0.0.1:8000/sse
```
For stdio:
```bash
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:
```bash
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.
## Privacy Policy
This connector is operated by EOD Historical Data (Unicorn Data Services). It sends the
parameters you provide (for example tickers, date ranges, and your API key) to the EODHD
APIs to fulfil each request, and returns the responses to your MCP client. It does not
collect or store conversation content beyond what is required to serve a request.
Full privacy policy: https://eodhd.com/financial-apis/privacy-policy
