Metadata-Version: 2.4
Name: 0xchron-polymarket-mcp
Version: 0.1.0
Summary: Read-only Polymarket prediction market data for AI agents (MCP server).
Project-URL: Repository, https://github.com/0xChron/polymarket-mcp
Author: Aaron Canillas
License: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: dotenv>=0.9.9
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp>=1.27.2
Requires-Dist: pydantic-settings>=2.14.1
Description-Content-Type: text/markdown

# Polymarket MCP

MCP server that exposes read-only Polymarket prediction market data to AI agents. Tools wrap Polymarket's public **Gamma** (market discovery) and **Data** (positions, portfolio, leaderboard) APIs. There is no CLOB integration — this server cannot place trades or read order books.

<!-- mcp-name: io.github.0xChron/polymarket-mcp -->

## Tools

| Tool | Description |
|------|-------------|
| `search_markets` | Search markets by title or description |
| `get_market_details` | Full details for a single market (by slug or Polymarket URL) |
| `get_user_positions` | Open positions for a wallet address |
| `get_user_performance` | Portfolio value, P&L, volume, and leaderboard rank |

All tools return markdown formatted for agent consumption. No API keys or wallet signing are required.

## Requirements

- Python 3.12+
- [uv](https://docs.astral.sh/uv/) (recommended) or Docker

## Quick start

Clone the repo, install dependencies, and start the server:

```bash
git clone https://github.com/0xChron/polymarket-mcp.git
cd polymarket-mcp
uv sync
make run
```

The server listens on **streamable HTTP** at `http://127.0.0.1:8000/mcp`.

Verify it is running with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```bash
make inspector
```

Connect the inspector to `http://localhost:8000/mcp` using the **Streamable HTTP** transport.

## Connect from an MCP client

This server uses the **streamable-http** transport (not stdio). Start the server first, then point your client at the `/mcp` endpoint.

### Cursor

Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project-scoped):

```json
{
  "mcpServers": {
    "polymarket": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

Restart Cursor (or reload the window) after saving. The server must be running before the client connects.

### Claude Desktop / other HTTP clients

Any MCP client that supports streamable HTTP can connect to the same URL. Refer to your client's documentation for remote server configuration.

### Example agent prompts

Once connected, an agent can call tools naturally:

- "Search Polymarket for active markets about Bitcoin ETFs"
- "Get details for https://polymarket.com/event/will-bitcoin-hit-100k"
- "Show open positions for wallet `0x…`"
- "What is the all-time P&L and leaderboard rank for `0x…`?"

## Docker

Build and run the container:

```bash
make build
docker run --rm -p 8000:8000 -e FASTMCP_HOST=0.0.0.0 polymarket-mcp
```

`FASTMCP_HOST=0.0.0.0` is required so the server accepts connections from outside the container. Then connect your MCP client to `http://localhost:8000/mcp`.

## Configuration

Optional environment variables override API endpoints and server settings:

| Variable | Default | Description |
|----------|---------|-------------|
| `GAMMA_URL` | `https://gamma-api.polymarket.com` | Gamma API base URL |
| `DATA_URL` | `https://data-api.polymarket.com` | Data API base URL |
| `DEFAULT_TIMEOUT` | `15` | HTTP request timeout (seconds) |
| `FASTMCP_HOST` | `127.0.0.1` | Bind address (`0.0.0.0` for Docker) |
| `FASTMCP_PORT` | `8000` | Listen port |

## Development

```bash
make run        # Start the server
make test       # Run tests
make inspector  # Open MCP Inspector
make build      # Build Docker image
```

See [`docs/PROJECT_KNOWLEDGE_BASE.md`](docs/PROJECT_KNOWLEDGE_BASE.md) for architecture, conventions, and how to add new tools.

## Publishing to the MCP Registry

The [MCP Registry](https://modelcontextprotocol.io/registry/about) hosts server metadata so clients can discover and install MCP servers. This project is set up for GitHub-based publishing under the name `io.github.0xChron/polymarket-mcp`.

### 1. Publish a package artifact

The registry stores metadata only — you must publish the server to a supported package registry first. Options:

**PyPI** (recommended for Python users):

1. Ensure this README contains the ownership marker (already included above as an HTML comment).
2. Publish to [PyPI](https://pypi.org): `uv build && uv publish`
3. Users can then run with `uvx 0xchron-polymarket-mcp` after the package is available.

**Docker (OCI)**:

1. Push the image to a public registry (e.g. Docker Hub or GHCR).
2. Add the registry label to your image:

   ```dockerfile
   LABEL io.modelcontextprotocol.server.name="io.github.0xChron/polymarket-mcp"
   ```

### 2. Create `server.json`

Install the publisher CLI and generate a template:

```bash
brew install mcp-publisher
# or: curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher && sudo mv mcp-publisher /usr/local/bin/

mcp-publisher init
```

Edit `server.json` — example for a PyPI package with streamable HTTP:

```json
{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.0xChron/polymarket-mcp",
  "description": "Read-only Polymarket prediction market data for AI agents.",
  "repository": {
    "url": "https://github.com/0xChron/polymarket-mcp",
    "source": "github"
  },
  "version": "0.1.0",
  "packages": [
    {
      "registryType": "pypi",
      "registryBaseUrl": "https://pypi.org",
      "identifier": "0xchron-polymarket-mcp",
      "version": "0.1.0",
      "runtimeHint": "uvx",
      "transport": {
        "type": "streamable-http",
        "url": "http://localhost:8000/mcp"
      }
    }
  ]
}
```

For a Docker image, use `"registryType": "oci"` and set `"identifier"` to your image reference (e.g. `ghcr.io/0xchron/polymarket-mcp:0.1.0`).

The `name` in `server.json` must match the `mcp-name` in this README (PyPI) or the Docker label (OCI).

### 3. Authenticate and publish

```bash
mcp-publisher login github
mcp-publisher publish --dry-run   # validate first
mcp-publisher publish
```

With GitHub auth, the server name must start with `io.github.0xChron/`. See the [registry quickstart](https://modelcontextprotocol.io/registry/quickstart) for full details.

## License

MIT — see [LICENSE](LICENSE).
