# pytheum-mcp

MCP server for the pytheum prediction-market context API.

> On PyPI as `pytheum-mcp`. Source: [github.com/pytheum/pytheum-mcp](https://github.com/pytheum/pytheum-mcp). Docs: [github.com/pytheum/pytheum-doc](https://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)

```bash
# 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](./npm/README.md) for the install one-liner).

### Via PyPI (Python-native)

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

Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).

## Configure

### Claude Desktop

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

```json
{
  "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:

```json
{
  "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`](https://github.com/pytheum/pytheum-doc). The machine-readable OpenAPI spec is at [`openapi.yaml`](https://github.com/pytheum/pytheum-doc/blob/main/openapi.yaml).

## License

MIT