📊 Polymarket MCP Server

📖 Overview

The Polymarket MCP Server enables AI agents to interact with Polymarket, 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

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)

{
  "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

pnpm run build

👁️ Development Mode (Watch)

pnpm run watch

✅ Linting & Formatting

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
• Model Context Protocol (MCP)
• Polymarket Platform

⚠️ 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