polymarket-mcp
Polymarket MCP server enables AI agents to discover prediction markets, inspect pricing/order books, and optionally trade and manage a Polymarket portfolio.
Search, list, and filter markets/events by query, slug, tag, or active status.
Get all tags and detailed market/event metadata.
View live order books and implied probabilities for outcome tokens.
Track positions, balances, allowances, open orders, and trade history for a wallet/authenticated account.
With a private key, place limit or market orders, cancel individual/all orders, approve/update allowances, and redeem resolved positions.
Enforce optional per-order and per-session pUSD spending limits for trading.
The provided schema directly exposes read-only market discovery, metadata, tag, and order-book tools.
Provides trading and on-chain interaction capabilities on the Polygon network, using a configurable Polygon RPC URL (with CHAIN_ID defaulting to 137) to sign and broadcast orders, approve pUSD and Conditional Token allowances, and manage balances/allowances for Polymarket V2 markets.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@polymarket-mcp search for markets related to crypto"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
📊 Polymarket MCP Server
📖 Overview
The Polymarket MCP Server enables AI agents to interact with Polymarket, a leading prediction market platform on Polygon. This server provides comprehensive access to market data, real-time pricing, order books, and trading capabilities through the Polymarket API.
By implementing the Model Context Protocol (MCP), this server allows Large Language Models (LLMs) to discover prediction markets, analyze odds (probabilities), execute trades, and track portfolio positions directly through their context window, bridging the gap between AI and decentralized prediction markets.
Related MCP server: Polymarket MCP Server
✨ Features
Market Discovery: Search and filter prediction markets by keywords, tags, and status.
Real-time Pricing: Access live price data, implied probabilities, and depth-of-market (order books) for any outcome token.
Trading Capabilities: Place limit orders, market orders, and manage open orders (requires private key).
Portfolio Tracking: Monitor user positions, trade history, and balances for specific wallet addresses.
Order Management: View, cancel, and manage open orders across all markets.
📦 Installation
🚀 Using npx (Recommended)
To use this server without installing it globally:
npx @iqai/mcp-polymarket🔧 Build from Source
git clone https://github.com/IQAIcom/mcp-polymarket.git
cd mcp-polymarket
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": "npx",
"args": ["-y", "@iqai/mcp-polymarket"]
}
}
}⚙️ Advanced Configuration (With Trading)
{
"mcpServers": {
"polymarket": {
"command": "npx",
"args": ["-y", "@iqai/mcp-polymarket"],
"env": {
"POLYMARKET_PRIVATE_KEY": "your_private_key_here",
"POLYGON_RPC_URL": "https://polygon-mainnet.g.alchemy.com/v2/<YOUR_KEY>"
}
}
}
}🔐 Configuration (Environment Variables)
Variable | Required | Description | Default |
| No | Private key for trading (enables trading tools) | - |
| No | Polygon RPC URL for transactions |
|
| No | Polymarket CLOB API base URL |
|
| No | Blockchain network chain ID |
|
| No | Order signature type ( |
|
| No | Funder address for transactions | - |
| No | Alternative funder address (alias) | - |
| No | Max pUSD notional for a single order. Larger orders are rejected before signing. | No limit |
| No | Max cumulative pUSD notional across all orders while the server runs | No limit |
🛡️ Spending limits
Many MCP hosts can be set to auto-approve tool calls. In that mode nothing but the wallet balance stops an agent from placing an order of any size, so set limits whenever trading is enabled:
"env": {
"POLYMARKET_PRIVATE_KEY": "your_private_key_here",
"POLYMARKET_MAX_ORDER_USD": "25",
"POLYMARKET_MAX_SESSION_USD": "100"
}The server enforces these itself, next to the key, so they hold whatever host or agent is calling. Order notional is measured in pUSD:
Limit orders (
place_order):price × sizeMarket BUY (
place_market_order):amountMarket SELL (
place_market_order):amount × best bid, the most the sale can return
An order over a limit comes back as an ORDER_LIMIT_EXCEEDED result and is never signed or sent. The session total counts every order the exchange accepted, including limit orders that are later cancelled, and resets when the server restarts. Malformed values stop the server at startup rather than silently disabling a limit.
Trading tools also carry the MCP destructiveHint annotation, so hosts that respect it will ask before running them.
💡 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 pUSD 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
approve_allowances
Grant the pUSD and Conditional Token approvals required for Polymarket V2 trading and position management. Automatically approves only contracts that do not already have permission. Approvals are revocable at any time in your wallet.
Parameter | Type | Required | Description |
| integer | false | How many confirmations to wait before returning (0 = return immediately after broadcasting). Default: 0 |
cancel_all_orders
Cancel all open orders for the authenticated account.
No parameters
cancel_order
Cancel a specific order by its ID.
Parameter | Type | Required | Description |
| string | true | The unique identifier of the order to cancel |
get_all_tags
Get a list of all available tags for categorizing markets.
No parameters
get_balance_allowance
Get balance and allowance information for the authenticated account. Can check COLLATERAL or CONDITIONAL tokens.
Parameter | Type | Required | Description |
| string | true | Asset type to check balance for: COLLATERAL or CONDITIONAL |
| string | false | Optional token ID for conditional token balance |
get_event_by_slug
Get detailed information about a specific event by its slug identifier. Events group multiple related markets.
Parameter | Type | Required | Description |
| string | true | The event slug identifier |
get_market_by_slug
Get detailed information about a specific market by its slug identifier. The slug can be extracted from the Polymarket URL.
Parameter | Type | Required | Description |
| string | true | The market slug identifier (e.g., 'will-trump-win-2024') |
get_markets_by_tag
Get markets filtered by a specific tag ID. Useful for finding markets in specific categories.
Parameter | Type | Required | Default | Description |
| string | true | The tag ID to filter by | |
| number | false | 20 | Number of markets to return (default: 20) |
| boolean | false | false | Include closed markets (default: false) |
get_open_orders
Get all open orders for the authenticated account. Can optionally filter by market.
Parameter | Type | Required | Description |
| string | false | Optional market address to filter orders by |
get_order
Get details of a specific order by its ID.
Parameter | Type | Required | Description |
| string | true | The unique identifier of the order |
get_order_book
Get the current order book for a specific market token. Shows all active buy and sell orders.
Parameter | Type | Required | Description |
| string | true | The token ID for the market outcome |
get_positions
Get all positions for a wallet address with current values. Returns position details including size, current price, current value, and P&L. Uses the Polymarket Data API for accurate position valuation.
Parameter | Type | Required | Default | Description |
| string | false | Wallet address to fetch positions for. If not provided, uses POLYMARKET_FUNDER env var. | |
| number | false | 100 | Maximum number of positions to return (default: 100) |
get_trade_history
Get trade history for the authenticated account. Can optionally filter by market or maker address.
Parameter | Type | Required | Description |
| string | false | Optional market address to filter trades by |
| string | false | Optional maker address to filter trades by |
list_active_markets
List all currently active markets with pagination. Returns markets that are not yet closed.
Parameter | Type | Required | Default | Description |
| number | false | 20 | Number of markets to return (default: 20, max: 100) |
| number | false | 0 | Number of markets to skip for pagination (default: 0) |
place_market_order
Place a market order that executes immediately at the current market price. For BUY orders, amount is the pUSD amount to spend. For SELL orders, amount is the number of shares to sell. Example: amount=5, side=BUY spends 5 pUSD. Minimum 1 pUSD for BUY orders. Rejected without being sent if it exceeds the server spending limits (POLYMARKET_MAX_ORDER_USD / POLYMARKET_MAX_SESSION_USD).
Parameter | Type | Required | Description |
| string | true | The token ID of the market outcome to trade |
| number | true | BUY orders: pUSD amount to spend. SELL orders: Number of shares to sell. Minimum 1 pUSD for BUY orders. |
| string | true | The side of the order: BUY or SELL |
| string | false | Order type: FOK (Fill or Kill) or FAK (Fill and Kill). Default: FOK |
place_order
Place a limit order on Polymarket at a specific price. Specify the number of shares (size) and price (0-1). For both BUY and SELL, you specify the number of shares you want to trade. Example: size=10, price=0.6 means buy/sell 10 shares at $0.60 per share (total: $6). Rejected without being sent if it exceeds the server spending limits (POLYMARKET_MAX_ORDER_USD / POLYMARKET_MAX_SESSION_USD).
Parameter | Type | Required | Description |
| string | true | The token ID of the market outcome to trade |
| number | true | The limit price for the order (between 0 and 1). This is the probability/price per share. |
| number | true | Number of shares to trade. For both BUY and SELL orders, this is always the number of outcome tokens/shares. |
| string | true | The side of the order: BUY or SELL |
| string | false | Order type: GTC (Good Till Cancelled) or GTD (Good Till Date). Default: GTC |
redeem_positions
Redeem all winning outcome tokens from a resolved Polymarket market into pUSD. Provide the conditionId and set negRisk=true for negative-risk markets.
Parameter | Type | Required | Default | Description |
| string | true | The condition ID for the resolved market. This is typically a 32-byte hex string. | |
| boolean | false | false | Whether this is a negative-risk market. Selects the V2 NegRisk collateral adapter when true. Default: false |
search_markets
Search for markets, events, and profiles using text search.
Parameter | Type | Required | Description |
| string | true | Search query text |
update_balance_allowance
Update balance and allowance for the authenticated account. Required before trading.
Parameter | Type | Required | Description |
| string | true | Asset type to update allowance for: COLLATERAL or CONDITIONAL |
| string | false | Optional token ID for conditional token |
👨💻 Development
🏗️ Build Project
pnpm run build👁️ Development Mode (Watch)
pnpm run watch🧪 Tests
pnpm test✅ Linting & Formatting
pnpm run lint
pnpm run format📁 Project Structure
src/tools/: Individual tool definitionssrc/services/: API client and business logicsrc/index.ts: Server entry point
📚 Resources
⚠️ 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
Available Tools
7 toolsget_all_tagsA
Get a list of all available tags for categorizing markets.
Inputs: no named parameters.
get_event_by_slugA
Get detailed information about a specific event by its slug identifier. Events group multiple related markets.
Inputs: slug (required).
get_market_by_slugA
Get detailed information about a specific market by its slug identifier. The slug can be extracted from the Polymarket URL.
Inputs: slug (required).
get_markets_by_tagB
Get markets filtered by a specific tag ID. Useful for finding markets in specific categories.
Inputs: tag_id (required), limit, closed.
get_order_bookB
Get the current order book for a specific market token. Shows all active buy and sell orders.
Inputs: token_id (required).
list_active_marketsA
List all currently active markets with pagination. Returns markets that are not yet closed.
Inputs: limit, offset.
search_marketsB
Search for markets, events, and profiles using text search.
Inputs: query (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a clearly distinct purpose: tags, events, markets, order book, listing, and search. No overlapping functionality.
All tools follow a consistent verb_noun pattern using snake_case (get_, list_, search_).
7 tools is well-scoped for a prediction market querying server, covering essential data access without being too few or too many.
Covers listing, searching, details, tags, and order book. Minor gap: no direct price or historical data, but adequate for common queries.
Maintenance
Related MCP Connectors
Polymarket in your AI: market rules, real fill costs, who is trading, top traders. Read-only.
Calibrated world model for AI agents. 40 tools: world state, markets, trading. Kalshi + Polymarket.
Trade Polymarket prediction markets from your Ask Gina wallet. Moves real funds.
Polymarket wallet intelligence for AI agents: scored wallets, insider signals, whale flow.
Related MCP Servers
- AlicenseBqualityNot gradedmaintenanceEnables AI agents to interact with the Polymarket prediction market platform to discover markets, analyze real-time pricing, and monitor public portfolio data. It provides comprehensive access to market analytics, implied probabilities, and order books through the Model Context Protocol.5932 npm-
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with Polymarket prediction markets, including retrieving market data, user positions, and trading history.823 npm13Apache 2.0
- AlicenseAqualityDmaintenanceProvides search, trending, odds, arbitrage, and category browsing for prediction markets (Polymarket & Kalshi) via the Model Context Protocol, enabling AI agents to access live market data without API keys.51MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to discover prediction markets, view real-time data, execute trades (market/limit orders), and manage portfolios on Polymarket.632 npm3MIT