The official MCP server for HF Market Data — 1-minute to daily bars for stocks, ETFs, futures, crypto, indices and FX since 2007, individual futures contracts, custom continuous series, term structures, options chains with Greeks and point-in-time SEC fundamentals, straight into Claude Code, Cursor, Codex or any MCP client.
: [Docs: …]`, whether the API answered with the v2 `{"error":{code,message,docs}}` envelope or the legacy `{"detail"}`.
- `subscribe_filings` is bounded by design (`max_messages` ≤ 100, `timeout_seconds` ≤ 120) and closes the socket when it returns; it needs Node ≥ 22 (global `WebSocket`) or Node 20 with `--experimental-websocket`.
- Read-only: no tool ever writes anything anywhere.
## Configuration snippets
### Claude Code
```bash
claude mcp add hfmarketdata -e HFMD_API_KEY=hfmd_live_… -- npx -y hfmarketdata-mcp
# tarball install instead of npm:
npm i -g https://www.hfmarketdata.io/downloads/hfmarketdata-mcp-1.0.0.tgz && claude mcp add hfmarketdata -e HFMD_API_KEY=hfmd_live_… -- hfmarketdata-mcp
```
Or in `.mcp.json` at the root of a project (shared with your team):
```json
{
"mcpServers": {
"hfmarketdata": {
"command": "npx",
"args": ["-y", "hfmarketdata-mcp"],
"env": { "HFMD_API_KEY": "hfmd_live_…" }
}
}
}
```
### Cursor — `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global)
```json
{
"mcpServers": {
"hfmarketdata": {
"command": "npx",
"args": ["-y", "hfmarketdata-mcp"],
"env": { "HFMD_API_KEY": "hfmd_live_…" }
}
}
}
```
One-click (best effort): `cursor://anysphere.cursor-deeplink/mcp/install?name=hfmarketdata&config=` — generated for you on .
### Codex — `~/.codex/config.toml`
```toml
[mcp_servers.hfmarketdata]
command = "npx"
args = ["-y", "hfmarketdata-mcp"]
env = { HFMD_API_KEY = "hfmd_live_…" }
```
### Claude Desktop — `claude_desktop_config.json`
```json
{ "mcpServers": { "hfmarketdata": { "command": "npx", "args": ["-y", "hfmarketdata-mcp"], "env": { "HFMD_API_KEY": "hfmd_live_…" } } } }
```
Keyless? Simply drop the `env` block.
## Example session
```
> Compare ESZ25 and ESH26 over 30 days
⏺ get_coverage(kind="futures_contract", symbol="ESZ25") … get_bars(asset="futures_contract", symbol="ESZ25", start="2025-08-05") …
⏺ Over the last 30 sessions ESH26 traded at a 61.5 → 58.0 point premium to ESZ25 (calendar spread narrowing 3.5 pts as
financing expectations eased). Volume is still 96 % in ESZ25; the roll window usually opens ~8 sessions before the
December expiry (2025-12-19). One session (2025-09-01, Labor Day) is missing in both legs — not interpolated.
```
## Development
```bash
npm install
npm test # vitest — 45 tests, every tool mocked (fetch + websocket)
npm run build # tsc → dist/
node dist/index.js --selftest
node scripts/live-smoke.mjs # real stdio round-trip against www.hfmarketdata.io
npm run inspect # MCP Inspector UI
```
### Release
```bash
npm version 1.0.x
npm run build && npm test
npm pack # → hfmarketdata-mcp-1.0.x.tgz (this is what /downloads serves)
npm publish --dry-run # inspect the file list
npm publish --access public # requires the maintainer's npm login (npm login / NPM_TOKEN)
```
Until the package is on the npm registry, `npx -y hfmarketdata-mcp` resolves nothing: use the tarball URL above or `npm i -g ./hfmarketdata-mcp-1.0.0.tgz`.
## Project layout
```
src/index.ts bin — stdio transport, --help/--version/--selftest
src/server.ts createServer(): 14 tools · 2 resources · 3 prompts
src/tools.ts tool catalogue (zod schemas + handlers), runTool()
src/client.ts fetch wrapper: auth, format=json, rate headers, uniform HfmdError
src/format.ts compact tables, head/tail summaries
src/stream.ts bounded websocket consumer
src/resources.ts hfmarketdata://status · hfmarketdata://limits
src/prompts.ts term-structure-analysis · compare-contracts · fundamentals-snapshot
test/ vitest (mocked fetch + fake WebSocket + in-memory MCP transport)
scripts/ live-smoke.mjs · record-demo.md
```
## Licence
MIT © Simon-Pierre Boucher — data by [FirstRate Data](https://firstratedata.com) and SEC EDGAR, served by [HF Market Data](https://www.hfmarketdata.io). Questions: contact@spboucher.ai.