Metadata-Version: 2.4
Name: pytheum-mcp
Version: 0.1.0
Summary: MCP server for the pytheum prediction-market context API.
Project-URL: Homepage, https://api.pytheum.com
Project-URL: Repository, https://github.com/pytheum/pytheum-mcp
Project-URL: Documentation, https://github.com/pytheum/pytheum-doc
Author-email: pytheum <dev@pytheum.com>
License: MIT
License-File: LICENSE
Keywords: ai-agents,kalshi,mcp,model-context-protocol,polymarket,prediction-markets
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: mcp[cli]>=1.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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
