Siftingio Python

siftingio-mcp-python MCP server

A Model Context Protocol (MCP) server that exposes the SiftingIO market-data SDK (siftingio) to your AI assistant. With it running, the model can pull live prices, read SEC/EDGAR fundamentals, fetch OHLCV bars, look up 13F holdings, check market status, and scan the macro economic calendar.

It's a Python port of siftingio-mcp (the TypeScript server), built on FastMCP.

Setup

Requires Python 3.13+.

python -m venv .venv && source .venv/bin/activate
pip install -e .

You'll need an API key from https://sifting.io:

export SIFTING_API_KEY=sft_...

To point at a different backend, override the defaults with SIFTING_BASE_URL and SIFTING_WS_URL.

For local development, copy .env.example to .env and load it however you like (e.g. set -a; . ./.env; set +a, or direnv). When you wire this into a real MCP client, pass the key through the server's env block instead of a file — there's an example below.

Run

The commands:

• siftingio-mcp — run the server over stdio (the default transport).
• siftingio-mcp-http — run it over Streamable HTTP.
• python -m siftingio_mcp — same as siftingio-mcp, without the console script.
• pytest — run the tests.
• ruff check / ruff format — lint and format.
• mypy — type-check.

CI (.github/workflows/ci.yml) runs the same steps on every push and PR: format check, lint, typecheck, test.

Note that the server speaks JSON-RPC over stdio, so stdout is reserved for the protocol. Diagnostics go to stderr.

Inspect interactively

The MCP inspector is the easiest way to try the server by hand:

SIFTING_API_KEY=sft_... npx @modelcontextprotocol/inspector siftingio-mcp

HTTP (Streamable HTTP) transport

For a remote or hosted deployment, use MCP's Streamable HTTP transport instead of stdio:

SIFTING_API_KEY=sft_... PORT=3000 siftingio-mcp-http
# → MCP endpoint at http://127.0.0.1:3000/mcp  (POST messages, GET SSE, DELETE session)

It's stateful: each client gets its own session (tracked by the mcp-session-id header), while the upstream SiftingIO connection is shared across the process. It only binds to loopback and rejects non-local browser Origins for DNS-rebinding protection. Set the port with PORT (or MCP_HTTP_PORT); the default is 3000.

For auth, set MCP_AUTH_TOKEN and the server will require Authorization: Bearer <token> on every request (a missing or wrong token gets a 401). Put a reverse proxy in front to handle TLS and the token, and you can expose the server past localhost:

MCP_AUTH_TOKEN=s3cret SIFTING_API_KEY=sft_... siftingio-mcp-http

Then point any HTTP-capable MCP client at http://127.0.0.1:3000/mcp:

claude mcp add --transport http siftingio http://127.0.0.1:3000/mcp

Use with an MCP client

Add this to your client config — Claude Desktop's claude_desktop_config.json, for example, or use claude mcp add on Claude Code:

{
  "mcpServers": {
    "siftingio": {
      "command": "siftingio-mcp",
      "env": { "SIFTING_API_KEY": "sft_..." }
    }
  }
}

If siftingio-mcp isn't on the client's PATH, use the absolute path to the console script (/path/to/.venv/bin/siftingio-mcp) or python -m siftingio_mcp.

Tools (36)

Namespace	Tools
Live (snapshot)	last_trade, last_quote, last_tvl
Stocks	stocks_search, stocks_profile, stocks_filings, stocks_filing, stocks_sections, stocks_section, stocks_risk_factors_diff, stocks_ratios, stocks_earnings, stocks_financials, stocks_financial_concept, stocks_insiders, stocks_ownership, stocks_events, stocks_compensation, stocks_screener, stocks_bars
Crypto / Forex	crypto_bars, forex_bars
DEX	dex_wallet
Markets	markets_list, markets_status_all, markets_status, markets_hours, markets_calendar
Filers	filers_holdings
Macro	economic_calendar_list
Live (stream)	ws_subscribe, ws_unsubscribe, ws_poll, ws_collect, ws_status, ws_disconnect

A few patterns to know about:

Paginated tools take cursor/limit and return a meta.next_cursor to fetch the next page. The stocks_* list tools — stocks_filings, stocks_earnings, stocks_insiders, stocks_ownership, stocks_events, stocks_compensation — also accept max_items: set it and they auto-paginate, gathering up to that many items across pages in one call.

The high-traffic tools (last_trade, last_quote, last_tvl, stocks_profile, stocks_search) have an output schema and return structuredContent alongside the human-readable text, so clients can read them machine-side too.

Every tool also carries MCP annotations. The data tools are readOnlyHint: true (and openWorldHint: true, since they reach an external API), while the WebSocket tools that change connection state are readOnlyHint: false, destructiveHint: false.

Results are size-capped at roughly 60k characters (see MAX_RESULT_CHARS in siftingio_mcp/util.py). When a heavy endpoint — full XBRL financials, screeners, OHLCV bars — returns more than that, the server trims its largest array and adds a _truncated note explaining how to narrow the query.

Note on from/to: since from is a reserved word in Python, the date lower-bound input field is named from_ (matching the SiftingIO SDK's own convention). to is unchanged.

Live WebSocket streaming

Streaming doesn't fit a single request/response, so the server keeps one persistent WebSocket open, buffers frames as they arrive, and the tools read from that buffer. Channels (the product field) are cex (crypto), dex (DEX trades), fx (forex), us (US stocks), and tvl (DEX pool TVL).

There are two ways to use it:

• Subscribe + poll, for ongoing streams: call ws_subscribe once, then keep calling ws_poll. The first poll returns a recent tail; feed the returned next_seq back in as after_seq to get only newer frames after that. ws_status shows the connection and current subscriptions, and ws_disconnect shuts it down.
• Collect, for a quick one-shot: ws_collect subscribes, waits up to duration_ms (or until it has seen max frames), returns what it caught, and cleans up any subscription it created. Good for grabbing a few seconds of BTCUSD.

The connection reconnects on its own and replays your subscriptions when it does. The buffer is a rolling window, so the oldest frames eventually fall off; when they do, you'll see it reported through dropped/gap.

Prompts

These are guided, multi-tool workflows your client can surface as slash-commands:

• company_snapshot (ticker) — pulls stocks_profile, stocks_ratios, the latest stocks_filings, and last_trade into one briefing.
• compare_companies (tickers) — lines up several tickers side by side across the key ratios.
• market_now — what's open and closed right now, plus the high-impact macro events coming up.

Logging & shutdown

The server logs structured records about the connection (WebSocket open/close/reconnect/error) and shutdown to stderr (stdout is reserved for the protocol on the stdio transport).

On SIGINT or SIGTERM, it closes the live WebSocket and shuts down cleanly before exiting.

License

MIT