# 📊 Polymarket MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

## 📖 Overview

The Polymarket MCP Server enables AI agents to interact with [Polymarket](https://polymarket.com), a prediction market platform on Polygon. This server provides read-only access to market data (Gamma API), real-time pricing and order books (CLOB public API), public user data (Data API), comments/profiles, and bridge quotes/status.

By implementing the Model Context Protocol (MCP), this server allows Large Language Models (LLMs) to discover prediction markets, analyze odds (probabilities), and monitor positions or activity from public data sources.

## ✨ Features

*   **Market Discovery**: Search and filter prediction markets by keywords, tags, status, and events.
*   **Real-time Pricing**: Access live price data, implied probabilities, and order books for any outcome token.
*   **Public Portfolio Data**: Monitor positions, trade history, and activity for specific wallet addresses (public Data API).
*   **Comments & Profiles**: Retrieve public profiles and market/event comments.
*   **Realtime Subscriptions**: Subscribe to price, orderbook, and resolution updates.
*   **Bridge Utilities**: Fetch supported assets and bridge quotes/status.

## 📦 Installation

### 🔧 Build from Source

```bash
git clone https://github.com/traderalvin1/polymarket-mcp.git
cd polymarket-mcp
pnpm install
pnpm run build
```

## ⚡ Running with an MCP Client

Add the following configuration to your MCP client settings (e.g., `claude_desktop_config.json`).

### 📋 Minimal Configuration (Read-Only)

```json
{
  "mcpServers": {
    "polymarket": {
      "command": "node",
      "args": ["/path/to/polymarket-mcp/dist/index.js"]
    }
  }
}
```

## 🔐 Configuration (Environment Variables)

| Variable | Required | Description | Default |
| :--- | :--- | :--- | :--- |
| `CLOB_API_BASE` | No | Polymarket CLOB API base URL | `https://clob.polymarket.com` |
| `CHAIN_ID` | No | Blockchain network chain ID | `137` (Polygon) |
| `GAMMA_API_URL` | No | Polymarket Gamma API base URL | `https://gamma-api.polymarket.com` |
| `DATA_API_URL` | No | Polymarket Data API base URL | `https://data-api.polymarket.com` |
| `BRIDGE_API_URL` | No | Polymarket Bridge API base URL | `https://bridge.polymarket.com` |

## 💡 Usage Examples

### 🔍 Market Discovery
*   "What are the most active prediction markets on Polymarket right now?"
*   "Search for markets related to 'Bitcoin' or 'BTC'."
*   "Find markets in the 'Crypto' category."
*   "What events are trending on Polymarket today?"

### 📊 Analytics & Pricing
*   "Show me the order book for the 2024 election market."
*   "What is the current probability implied by the price of the 'Yes' token?"
*   "Get detailed information about the 'will-trump-win-2024' market."

### 💼 Portfolio & Trading (Requires Private Key)
*   "What's my current USDC balance and allowance?"
*   "Show me all my open orders across all markets."
*   "Place a buy order for 100 shares at 0.65 price."
*   "Cancel all my open orders on this market."

## 🛠️ MCP Tools

Full tool documentation is maintained in:

- `TOOLS_REFERENCE.md` — complete tool list, parameters, dependencies, edge cases
- `USAGE_EXAMPLES.md` — workflows and example calls

For agents, call `get_tool_guide` to get a concise, runtime usage guide.

## 🙏 Credits

This project is based on and modified from:
- https://github.com/IQAIcom/mcp-polymarket

## 👨‍💻 Development

### 🏗️ Build Project
```bash
pnpm run build
```

### 👁️ Development Mode (Watch)
```bash
pnpm run watch
```

### ✅ Linting & Formatting
```bash
pnpm run lint
pnpm run format
```

### 📁 Project Structure
*   `src/tools/`: Individual tool definitions
*   `src/services/`: API client and business logic
*   `src/index.ts`: Server entry point

## 📚 Resources

*   [Polymarket API Documentation](https://docs.polymarket.com)
*   [Model Context Protocol (MCP)](https://modelcontextprotocol.io)
*   [Polymarket Platform](https://polymarket.com)

## ⚠️ Disclaimer

This project is an unofficial tool and is not directly affiliated with Polymarket. It interacts with financial and prediction market data. Users should exercise caution and verify all data independently. Trading in prediction markets involves risk.

## 📄 License

[MIT](LICENSE)