pytheum-mcp

MCP server for the pytheum prediction-market context API.

On PyPI as pytheum-mcp. Source: github.com/pytheum/pytheum-mcp. Docs: github.com/pytheum/pytheum-doc.

Wraps the four public endpoints on api.pytheum.com as MCP tools so AI agents (Claude Desktop, Cursor, anything that speaks MCP over stdio) can ask "which markets does this news article move?" without writing their own retrieval layer.

Install

Two install paths — both run the same Python code. Pick whichever your MCP client makes easier:

Via npm (recommended for Claude Desktop)

# no install needed — npx runs it
npx -y @pytheum/mcp

Claude Desktop ships a Node.js runtime but not Python, so npx is the path of least resistance there. The npm package is a small shim that runs uvx pytheum-mcp under the hood; uv is still required (see the npm README for the install one-liner).

Via PyPI (Python-native)

uvx pytheum-mcp                # one-shot
uv tool install pytheum-mcp    # permanent

Requires Python 3.11+ and uv.

Configure

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "pytheum": {
      "command": "npx",
      "args": ["-y", "@pytheum/mcp"],
      "env": {
        "PYTHEUM_API_BASE": "https://api.pytheum.com"
      }
    }
  }
}

Restart Claude Desktop. The hammer icon in the composer should list pytheum's tools.

Cursor / Windsurf / others

Same config under ~/.cursor/mcp.json (or the client's equivalent). If you already have uv on PATH, you can swap npx -y @pytheum/mcp for uvx pytheum-mcp to skip the Node shim entirely:

{
  "mcpServers": {
    "pytheum": {
      "command": "uvx",
      "args": ["pytheum-mcp"],
      "env": {
        "PYTHEUM_API_BASE": "https://api.pytheum.com"
      }
    }
  }
}

Tools

Tool	Endpoint	Description
t_find_markets(query, limit?, group_by?)	GET /v1/markets/relevant-to	Find markets matching free-text
t_market_context(market_ref, limit?)	GET /v1/markets/{ref}/context	Events paired with a market
t_bundle_context(bundle_ref, limit?)	GET /v1/bundles/{ref}/context	Events paired with any market in a bundle
t_event_related_markets(event_id, limit?)	GET /v1/events/{id}/related-markets	Markets related to a firehose event

Configuration

Env var	Default	Purpose
PYTHEUM_API_BASE	https://api.pytheum.com	Override to hit staging or a local stub

Reference

Endpoint schemas, response shapes, errors, and rate limits live in pytheum/pytheum-doc. The machine-readable OpenAPI spec is at openapi.yaml.

License

MIT