A comprehensive Model Context Protocol (MCP) server for interacting with Polymarket, the world's largest prediction market platform. This server provides seamless access to Polymarket's APIs, enabling AI assistants to retrieve market data, user positions, trading history, and more.
- Get Markets: Retrieve prediction markets with filtering and pagination
- Get Events: Access event data containing multiple related markets
- Market Prices: Real-time and historical price data with technical analysis
- Order Book: Live bid/ask data with market depth analysis
- Trade History: Comprehensive trading data with statistics
- User Positions: Portfolio tracking with P&L calculations
- User Activity: On-chain activity including trades, splits, merges, and rewards
- Market Holders: Ownership distribution and concentration analysis
- Liquidity analysis and market depth
- Price trend analysis and volatility metrics
- Portfolio performance tracking
- Market concentration and distribution insights
- Node.js 18+
- TypeScript 5.3+
- npm or yarn
-
Clone the repository
git clone <repository-url> cd polymarket-mcp
-
Install dependencies
npm install
-
Build the project
npm run build
-
Start the server
npm start
Add to your Claude Desktop configuration file:
Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"polymarket-mcp": {
"command": "node",
"args": ["path/to/polymarket-mcp/build/index.js"]
}
}
}-
Install Supergateway
npm install -g supergateway
-
Start SSE server
npm run sse
-
Configure Claude Desktop
{ "mcpServers": { "polymarket-mcp": { "type": "sse", "url": "http://localhost:3100/sse", "timeout": 600 } } }
get_markets({
limit?: number, // Max results (default: 20, max: 100)
offset?: number, // Pagination offset
active?: boolean, // Filter by active status
search?: string, // Search by title/description
order?: string, // Sort by: volume, liquidity, start_date, end_date
liquidity_min?: number, // Minimum liquidity threshold
volume_min?: number // Minimum volume threshold
})get_events({
limit?: number, // Max results (default: 20, max: 100)
offset?: number, // Pagination offset
active?: boolean, // Filter by active status
search?: string, // Search by title/description
order?: string // Sort by: volume, liquidity, start_date, end_date
})get_user_positions({
user_address: string, // Required: User's wallet address
limit?: number, // Max results (default: 50, max: 100)
market_id?: string, // Filter by specific market
min_size?: number, // Minimum position size
show_zero_positions?: boolean // Include zero positions
})get_user_activity({
user_address: string, // Required: User's wallet address
limit?: number, // Max results (default: 50, max: 100)
activity_type?: string, // TRADE, SPLIT, MERGE, REDEEM, REWARD, CONVERSION
side?: string, // BUY or SELL (for trades)
start_date?: string, // ISO 8601 date format
end_date?: string // ISO 8601 date format
})get_market_prices({
market_id?: string, // Market ID (required if no token_id)
token_id?: string, // Token ID (required if no market_id)
interval?: string, // 1m, 5m, 1h, 1d (default: 1h)
fidelity?: number, // Number of price points (default: 100, max: 1000)
include_orderbook?: boolean // Include current order book
})get_trades({
limit?: number, // Max results (default: 50, max: 100)
market_id?: string, // Filter by market
user_address?: string, // Filter by user
side?: string, // BUY or SELL
min_size?: number, // Minimum trade size
start_date?: string, // ISO 8601 date format
end_date?: string // ISO 8601 date format
})get_order_book({
market_id?: string, // Market ID (required if no token_id)
token_id?: string, // Token ID (required if no market_id)
depth?: number, // Price levels to show (default: 10, max: 50)
include_spread_analysis?: boolean, // Include spread analysis
include_liquidity_analysis?: boolean // Include liquidity analysis
})get_market_holders({
market_id?: string, // Market ID (required if no token_id)
token_id?: string, // Token ID (required if no market_id)
limit?: number, // Max results (default: 50, max: 100)
min_balance?: number, // Minimum balance threshold
include_user_info?: boolean // Include user profiles
})Show me the top 10 most liquid active prediction markets
Get positions for wallet address 0x1234... and show P&L analysis
Get order book for market ID abc123 with liquidity analysis
Show recent trades for market xyz789 with volume over 1000 shares
src/
├── index.ts # MCP server entry point
├── lib/
│ └── polymarketClient.ts # Polymarket API client
└── tools/ # Business logic tools
├── getMarkets.ts
├── getEvents.ts
├── getUserPositions.ts
├── getUserActivity.ts
├── getMarketPrices.ts
├── getTrades.ts
├── getOrderBook.ts
└── getMarketHolders.ts
This MCP server integrates with multiple Polymarket APIs:
- Gamma Markets API: Market data and metadata
- CLOB API: Order book and trading data
- Data API: User positions, activity, and analytics
Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Xingyu Chen
- LinkedIn: Xingyu Chen
- Email: guangxiangdebizi@gmail.com
- GitHub: @guangxiangdebizi
- NPM: @xingyuchen
- Polymarket for providing comprehensive APIs
- Model Context Protocol for the MCP framework
- The open-source community for inspiration and tools
Built with ❤️ for the prediction markets ecosystem