Click on "Install 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 Server show me the top 5 prediction markets by volume"
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.
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
Related MCP server: Polymarket MCP Server
Node.js 18+
TypeScript 5.3+
npm or yarn
Clone the repository
git clone <repository-url>
cd polymarket-mcpInstall dependencies
npm installBuild the project
npm run buildStart the server
npm startAdd 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 supergatewayStart SSE server
npm run sseConfigure 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 marketsGet positions for wallet address 0x1234... and show P&L analysisGet order book for market ID abc123 with liquidity analysisShow recent trades for market xyz789 with volume over 1000 sharessrc/
āāā 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.tsThis 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
Retrieve Polymarket events which contain multiple related markets. Events group markets around a common theme or topic.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of events to return (default: 20, max: 100) | |
| order | No | Field to sort by (volume, liquidity, start_date, end_date) | |
| active | No | Filter by active status - true for active events only | |
| closed | No | Filter by closed status - false to exclude closed events | |
| offset | No | Number of events to skip for pagination (default: 0) | |
| search | No | Search term to filter events by title or description | |
| tag_id | No | Filter events by specific tag/category ID | |
| archived | No | Filter by archived status - false to exclude archived events | |
| ascending | No | Sort direction - true for ascending, false for descending (default: false) | |
| volume_min | No | Minimum total volume threshold in USDC | |
| liquidity_min | No | Minimum total liquidity threshold in USDC |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states retrieval without disclosing any behavioral traits such as pagination limits, rate limits, or whether closed events are excluded by default. The minimal description fails to compensate for the lack of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. It is appropriately sized, though it could be more informative without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 optional parameters and no output schema, the description is minimal. It adequately states the purpose but lacks details on return structure or pagination behavior that would be helpful for such a parameter-rich tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all 11 parameters having descriptions. The tool description adds no additional meaning beyond what the schema already provides, resulting in a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves Polymarket events and explains events are groups of related markets. This distinguishes it from siblings like get_markets, which likely retrieve individual markets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use versus siblings. The name and description imply it is for events, but it does not specify when not to use or suggest alternatives like get_markets for individual markets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve holders and their positions for a specific market. Shows who owns shares and their holding amounts.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of holders to return (default: 50, max: 100) | |
| offset | No | Number of holders to skip for pagination (default: 0) | |
| order_by | No | Field to sort by (balance, percentage) | balance |
| token_id | No | Specific token/outcome ID within the market | |
| market_id | No | Market ID to get holders for | |
| min_balance | No | Minimum balance threshold to include holders | |
| order_direction | No | Sort direction (ASC or DESC) | DESC |
| include_user_info | No | Include additional user information if available (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It fails to disclose behavioral traits such as pagination limits, rate limits, authentication requirements, or error handling, only stating the basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundant words, efficiently conveying the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 8 parameters, no output schema, and no annotations, the description is too sparse. It fails to explain the meaning of returned fields like balance/percentage or how parameters interact, leaving the agent with insufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, so the description adds no additional meaning beyond the schema. The baseline score of 3 is appropriate as the schema already documents all parameters thoroughly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'retrieve' and the resource 'holders and their positions for a specific market', effectively differentiating it from sibling tools like 'get_markets' or 'get_user_positions'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving holder data but does not explicitly state when to use this tool versus alternatives like 'get_user_positions', nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current market prices and trading data for specific markets or tokens. Shows bid/ask spreads, last traded prices, and market depth.
| Name | Required | Description | Default |
|---|---|---|---|
| end_ts | No | End timestamp for historical prices (Unix timestamp) | |
| fidelity | No | Number of price points to return (default: 100, max: 1000) | |
| interval | No | Price interval for historical data (1m, 5m, 1h, 1d) | 1h |
| start_ts | No | Start timestamp for historical prices (Unix timestamp) | |
| token_id | No | Specific token/asset ID to get prices for | |
| market_id | No | Specific market ID to get prices for | |
| include_orderbook | No | Include current order book data (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions current prices and market depth but fails to clarify that parameters allow historical data retrieval (start_ts, end_ts, interval). The term 'current' is somewhat misleading given the historical capability. No disclosure of auth needs or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. First sentence states the main purpose, second lists key outputs. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Seven optional parameters and no output schema leave gaps. The description focuses on 'current' prices but the schema supports historical data, creating inconsistency. It does not explain default behavior (e.g., what happens when no parameters are given) or how token_id and market_id interact.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no extra meaning beyond the schema; parameters like 'market_id' and 'token_id' are self-explanatory. No additional context about parameter interactions or defaults is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves current market prices and trading data, listing specific outputs like bid/ask spreads, last traded prices, and market depth. It distinguishes from sibling tools such as 'get_markets' (which lists markets) and 'get_order_book' (which focuses solely on order book data).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for price and trading data but does not explicitly state when to choose this tool over alternatives like 'get_trades' or 'get_order_book'. No when-not-to-use or prerequisite information is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve Polymarket prediction markets with filtering and pagination options. Get market data including prices, volume, liquidity, and metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of markets to return (default: 20, max: 100) | |
| order | No | Field to sort by (volume, liquidity, start_date, end_date) | |
| active | No | Filter by active status - true for active markets only | |
| closed | No | Filter by closed status - false to exclude closed markets | |
| offset | No | Number of markets to skip for pagination (default: 0) | |
| search | No | Search term to filter markets by title or description | |
| tag_id | No | Filter markets by specific tag/category ID | |
| archived | No | Filter by archived status - false to exclude archived markets | |
| ascending | No | Sort direction - true for ascending, false for descending (default: false) | |
| volume_min | No | Minimum volume threshold in USDC | |
| liquidity_min | No | Minimum liquidity threshold in USDC |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a read operation without side effects. Since no annotations are provided, it carries full burden but only states that it retrieves data; no mention of rate limits, auth, or error behavior. Adequate for a simple read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The first sentence states the main purpose and features, making it immediately useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description mentions return fields (prices, volume, liquidity, metadata) but not the return type (list). Pagination behavior is implicit via parameters. Given no output schema and 11 optional parameters, the description is adequate but lacks explicit detail on output structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all parameters with descriptions (100% coverage). The description adds high-level context ('filtering and pagination') but does not enhance individual parameter meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve' and the resource 'Polymarket prediction markets', with specific mention of filtering and pagination. It distinguishes from siblings like get_events and get_market_prices by focusing on markets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. It does not specify exclusions or scenarios where sibling tools like get_events or get_market_prices would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve current order book data showing bids and asks for a specific market or token. Shows market depth and liquidity.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | Number of price levels to show for bids and asks (default: 10, max: 50) | |
| token_id | No | Token/asset ID to get order book for | |
| market_id | No | Market ID to get order book for | |
| include_spread_analysis | No | Include bid-ask spread analysis (default: true) | |
| include_liquidity_analysis | No | Include liquidity depth analysis (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral context. It only states the tool shows depth and liquidity but omits details like authentication requirements, rate limits, or output format, offering minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with two front-loaded sentences that immediately convey the tool's purpose and key features. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters and no output schema, the description is too sparse. It doesn't explain return structure, behavior when both identifiers are omitted, or how boolean flags affect output, leaving significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description does not need to repeat parameter details. However, it fails to clarify the relationship between token_id and market_id (e.g., whether one is required or how they interact), which the schema leaves ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as retrieving order book data (bids/asks) for a market or token, using specific verbs and resource. However, it doesn't explicitly differentiate itself from sibling tools like get_market_prices or get_trades, which could lead to confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not specify use cases, prerequisites, or exclusions, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve recent trades and trading history from Polymarket. Shows executed trades with prices, volumes, and market information.
| Name | Required | Description | Default |
|---|---|---|---|
| side | No | Filter trades by side (BUY or SELL) | |
| limit | No | Maximum number of trades to return (default: 50, max: 100) | |
| offset | No | Number of trades to skip for pagination (default: 0) | |
| asset_id | No | Filter trades by specific asset/token ID | |
| end_date | No | End date filter (ISO 8601 format: YYYY-MM-DD) | |
| max_size | No | Maximum trade size threshold | |
| min_size | No | Minimum trade size threshold | |
| order_by | No | Field to sort by (timestamp, size, price) | timestamp |
| market_id | No | Filter trades by specific market ID | |
| max_price | No | Maximum price threshold | |
| min_price | No | Minimum price threshold | |
| start_date | No | Start date filter (ISO 8601 format: YYYY-MM-DD) | |
| user_address | No | Filter trades by specific user address | |
| order_direction | No | Sort direction (ASC or DESC) | DESC |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description indicates it retrieves executed trades but lacks details on behavior such as pagination limits, default sorting, or whether trades are always recent. It does not contradict annotations (none present).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no extraneous information. The first sentence front-loads the purpose and resource, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 14 parameters and no output schema, the description is minimal. It mentions Polymarket and what data is returned, but does not cover common filtering patterns or how parameters interact. Adequate but incomplete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds general context ('prices, volumes, and market information') but does not elaborate on individual parameters beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve' and the resource 'trades and trading history', specifying what data is shown (prices, volumes, market information). It distinguishes from sibling tools like get_order_book or get_market_prices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives (e.g., get_order_book for current orders, get_market_prices for price history). Usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve user's on-chain activity history including trades, splits, merges, redeems, rewards, and conversions.
| Name | Required | Description | Default |
|---|---|---|---|
| side | No | Filter trades by side (BUY or SELL) | |
| limit | No | Maximum number of activities to return (default: 50, max: 100) | |
| offset | No | Number of activities to skip for pagination (default: 0) | |
| asset_id | No | Filter activities by specific asset/token ID | |
| end_date | No | End date filter (ISO 8601 format: YYYY-MM-DD) | |
| order_by | No | Field to sort by (timestamp, amount, price) | timestamp |
| market_id | No | Filter activities by specific market ID | |
| start_date | No | Start date filter (ISO 8601 format: YYYY-MM-DD) | |
| user_address | Yes | User's wallet address (proxy wallet address) | |
| activity_type | No | Filter by activity type | |
| order_direction | No | Sort direction (ASC or DESC) | DESC |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It lacks disclosure of pagination, rate limits, data freshness, or side effects. Only mentions retrieving history, which is insufficient for a tool with 11 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence with no wasted words. However, it omits useful context like pagination or sorting, which could be added without much bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no annotations. With 11 parameters including filters and pagination, the description is too brief to cover key capabilities. Should mention pagination (limit/offset) and sorting to help agents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema; it does not explain parameter interactions or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Retrieve' and the resource 'user's on-chain activity history', listing included activity types. It implies a broader scope than siblings like get_trades, but does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as get_trades or get_user_positions. The description does not provide context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve user's current positions in Polymarket prediction markets. Shows holdings, P&L, and position details.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of positions to return (default: 50, max: 100) | |
| offset | No | Number of positions to skip for pagination (default: 0) | |
| min_size | No | Minimum position size threshold | |
| market_id | No | Filter positions by specific market ID | |
| asset_type | No | Filter by asset type (conditional_token, collateral_token) | |
| user_address | Yes | User's wallet address (proxy wallet address) | |
| show_zero_positions | No | Include positions with zero size (default: false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions 'Shows holdings, P&L, and position details' but lacks behavioral details like pagination, error handling, or authorization requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with main action, no wasted words. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters and no output schema, the description is too brief. It doesn't explain return format, pagination, filtering behavior, or prerequisites, leaving significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters with descriptions (100% coverage), so description adds no additional param-level detail. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Retrieve user's current positions' with specific verb and resource, and distinguishes from sibling tools which focus on markets, events, activity, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives are mentioned, but the purpose is implied by the name and description. Lacks exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0get_eventsget_market_holdersget_market_pricesget_marketsget_order_bookget_tradesget_user_activityget_user_positionsScored across 8 tools
Each tool addresses a distinct aspect of Polymarket: markets, events, user positions, user activity, prices, trades, order book, and holders. No two tools have overlapping purposes.
All tools follow a consistent 'get_' prefix with a noun, making the verb_noun pattern predictable and clear.
8 tools cover the core read-only functionalities of a prediction market API without being excessive or insufficient.
The tool set covers market data, events, user positions, activity, trading history, order book, and holders. Missing write operations (e.g., placing bets) is acceptable for a read-only server, but a search or filter across all markets could be a minor gap.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Calibrated world model for AI agents. 40 tools: world state, markets, trading. Kalshi + Polymarket.
Live prediction markets: Polymarket + Kalshi prices, odds, order books. Pay-per-call USDC, no key.
Polymarket MCP ā prediction-market data via Gamma + CLOB public APIs.
Live Polymarket data for agents: markets, insider-scored whale trades, leaderboards, wallet P&L
