Skip to main content
Glama
Pytheum MCP

Pytheum MCP

Official
by pytheum

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:

# 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

Available Tools

4 tools
t_bundle_contextC

Events paired with any market inside a bundle, deduplicated by event_id.

Inputs: bundle_ref (required), limit.

t_find_marketsC

Find prediction markets matching a free-form text query (article body / news headline / question).

Inputs: query (required), limit, group_by.

t_market_contextC

Events (news/social/macro) paired with a specific market. market_ref accepts venue-prefixed id, slug, or URL.

Inputs: market_ref (required), limit.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool targets a distinct purpose: bundle context, event-related markets, free-text search, and market context. No overlap in functionality.

    Naming Consistency4/5

    All tools use a consistent 't_' prefix and snake_case, but not all follow a strict verb_noun pattern (e.g., 'bundle_context' is noun-like). Still highly uniform.

    Tool Count5/5

    Four tools is an ideal size for this domain—each tool serves a clear, non-redundant purpose without being too few or too many.

    Completeness5/5

    The tool set covers the core operations for retrieving prediction market data: search, context, and event linking. No obvious gaps for a read-oriented server.

    Related MCP Connectors