Skip to content
Back to search

polymarket-mcp-server

πŸ€– AI-Powered MCP Server for Polymarket - Enable Claude to trade prediction markets with 45 tools, real-time monitoring, and enterprise-grade safety features

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/caiovicentino--polymarket-mcp-server/badge.svg)](/listings/caiovicentino--polymarket-mcp-server)

HTML

<a href="/listings/caiovicentino--polymarket-mcp-server"><img src="/api/listings/caiovicentino--polymarket-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

One-Command Installation (Recommended)

**Try DEMO mode first** (no wallet needed):

# macOS/Linux
curl -sSL https://raw.githubusercontent.com/caiovicentino/polymarket-mcp-server/main/quickstart.sh | bash

# Or clone and run locally
git clone https://github.com/caiovicentino/polymarket-mcp-server.git
cd polymarket-mcp-server
./quickstart.sh

**Full installation** (with trading):

# macOS/Linux
./install.sh

# Windows
install.bat

The automated installer will: - βœ“ Check Python version (3.10+) - βœ“ Create virtual environment - βœ“ Install all dependencies - βœ“ Configure environment - βœ“ Set up Claude Desktop integration - βœ“ Test the installation

Installation Options

| Method | Command | Best For | |--------|---------|----------| | **Quick Start** | `./quickstart.sh` | First-time users, testing | | **DEMO Mode** | `./install.sh --demo` | No wallet, read-only access | | **Full Install** | `./install.sh` | Production trading setup | | **Windows** | `install.bat` | Windows users |

DEMO Mode vs Full Mode

**DEMO Mode** (No wallet required): - βœ… Market discovery and search - βœ… Real-time market analysis - βœ… AI-powered insights - βœ… Price monitoring - ❌ Trading disabled (read-only)

**Full Mode** (Requires Polygon wallet): - βœ… Everything in DEMO mode - βœ… Place orders and execute trades - βœ… Portfolio management - βœ… Position tracking - βœ… Real-time trade notifications

Manual Installation

If you prefer manual setup:

# Clone the repository
git clone https://github.com/caiovicentino/polymarket-mcp-server.git
cd polymarket-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the package
pip install -e .

Configuration

**Option 1: DEMO Mode** (easiest)

cp .env.example .env
# Edit .env and set:
DEMO_MODE=true

**Option 2: Full Trading Mode**

cp .env.example .env
# Edit with your Polygon wallet credentials
nano .env

**Required credentials (Full Mode):**

POLYGON_PRIVATE_KEY=your_private_key_without_0x_prefix
POLYGON_ADDRESS=0xYourPolygonAddress

**Recommended Safety Limits:**

MAX_ORDER_SIZE_USD=1000
MAX_TOTAL_EXPOSURE_USD=5000
MAX_POSITION_SIZE_PER_MARKET=2000
MIN_LIQUIDITY_REQUIRED=10000
MAX_SPREAD_TOLERANCE=0.05
ENABLE_AUTONOMOUS_TRADING=false
REQUIRE_CONFIRMATION_ABOVE_USD=500

With `ENABLE_AUTONOMOUS_TRADING=false` (the default), every order is held and returned as `confirmation_required` until you re-issue it with `confirm=true`. Set it to `true` to let orders under `REQUIRE_CONFIRMATION_ABOVE_USD` go through without that step.

Claude Desktop Integration

Add to your Claude Desktop configuration file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

{
  "mcpServers": {
    "polymarket": {
      "command": "/path/to/your/venv/bin/python",
      "args": ["-m", "polymarket_mcp.server"],
      "cwd": "/path/to/polymarket-mcp-server",
      "env": {
        "POLYGON_PRIVATE_KEY": "your_private_key",
        "POLYGON_ADDRESS": "0xYourAddress"
      }
    }
  }
}

**Restart Claude Desktop** and you're ready to trade! πŸŽ‰

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 589 lines Β· 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # πŸ€– Polymarket MCP Server
  2. [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
  4. [![MCP Protocol](https://img.shields.io/badge/MCP-1.0-purple.svg)](https://modelcontextprotocol.io)
  5. [![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](#testing)
  6. [![AgentSeal MCP](https://agentseal.org/api/v1/mcp/polymarket-mcp/badge)](https://agentseal.org/mcp/polymarket-mcp)
  7. **Complete AI-Powered Trading Platform for Polymarket Prediction Markets**
  8. Enable Claude to autonomously trade, analyze, and manage positions on Polymarket with 45 comprehensive tools, real-time WebSocket monitoring, and enterprise-grade safety features.
  9. ---
  10. ## πŸ‘¨β€πŸ’» Created By
  11. **[Caio Vicentino](https://github.com/caiovicentino)**
  12. Developed in collaboration with:
  13. - 🌾 **[Yield Hacker](https://opensea.io/collection/yield-hacker-pass-yhp)** - DeFi Innovation Community
  14. - πŸ’° **[Renda Cripto](https://rendacripto.com.br/)** - Crypto Trading Community
  15. - πŸ—οΈ **[Cultura Builder](https://culturabuilder.com/)** - Builder Culture Community
  16. Powered by **[Claude Code](https://claude.ai/code)** from Anthropic
  17. ---
  18. ## ⭐ Key Features
  19. ### 🎯 45 Comprehensive Tools Across 5 Categories
  20. <table>
  21. <tr>
  22. <td width="20%" align="center"><b>πŸ”<br/>Market Discovery</b><br/>8 tools</td>
  23. <td width="20%" align="center"><b>πŸ“Š<br/>Market Analysis</b><br/>10 tools</td>
  24. <td width="20%" align="center"><b>πŸ’Ό<br/>Trading</b><br/>12 tools</td>
  25. <td width="20%" align="center"><b>πŸ“ˆ<br/>Portfolio</b><br/>8 tools</td>
  26. <td width="20%" align="center"><b>⚑<br/>Real-time</b><br/>7 tools</td>
  27. </tr>
  28. </table>
  29. #### πŸ” Market Discovery (8 tools)
  30. - Search and filter markets by keywords, categories, events
  31. - Trending markets by volume (24h, 7d, 30d)
  32. - Category-specific markets (Politics, Sports, Crypto)
  33. - Markets closing soon alerts
  34. - Featured and promoted markets
  35. - Sports markets (NBA, NFL, etc.)
  36. - Crypto prediction markets
  37. #### πŸ“Š Market Analysis (10 tools)
  38. - Real-time prices and spreads
  39. - Complete orderbook depth analysis
  40. - Liquidity and volume metrics
  41. - Historical price data
  42. - **AI-powered opportunity analysis** with BUY/SELL/HOLD recommendations
  43. - Multi-market comparison
  44. - Top holders analysis
  45. - Risk assessment and scoring
  46. - Spread calculation and monitoring
  47. #### πŸ’Ό Trading (12 tools)
  48. - **Limit orders** (GTC, GTD, FOK, FAK)
  49. - **Market orders** (immediate execution)
  50. - Batch order submission
  51. - **AI-suggested pricing** (aggressive/passive/mid strategies)
  52. - Order status tracking and history
  53. - Open orders management
  54. - Single and bulk order cancellation
  55. - **Smart trade execution** (natural language β†’ automated strategy)
  56. - **Position rebalancing** with slippage protection
  57. - Order book integration
  58. #### πŸ“ˆ Portfolio Management (8 tools)
  59. - Real-time position tracking
  60. - P&L calculation (realized/unrealized)
  61. - Portfolio value aggregation
  62. - **Risk analysis** (concentration, liquidity, diversification)
  63. - Trade history with filters
  64. - On-chain activity log
  65. - Performance metrics
  66. - **AI-powered portfolio optimization** (conservative/balanced/aggressive)
  67. #### ⚑ Real-time Monitoring (7 tools)
  68. - Live price updates via WebSocket
  69. - Orderbook depth streaming
  70. - User order status notifications
  71. - Trade execution alerts
  72. - Market resolution notifications
  73. - Subscription management
  74. - System health monitoring
  75. - Auto-reconnect with exponential backoff
  76. ### πŸ›‘οΈ Enterprise-Grade Safety & Risk Management
  77. - βœ… **Order Size Limits** - Configurable maximum per order
  78. - βœ… **Exposure Caps** - Total portfolio exposure limits
  79. - βœ… **Position Limits** - Per-market position caps
  80. - βœ… **Liquidity Validation** - Minimum liquidity requirements
  81. - βœ… **Spread Tolerance** - Maximum spread checks before execution
  82. - βœ… **Confirmation Flow** - User confirmation for large orders
  83. - βœ… **Pre-trade Validation** - Comprehensive safety checks
  84. ### βš™οΈ Production-Ready Infrastructure
  85. - βœ… **L1 & L2 Authentication** - Wallet (private key) + API key auth
  86. - βœ… **Advanced Rate Limiting** - Token bucket algorithm respecting all Polymarket API limits
  87. - βœ… **EIP-712 Signing** - Secure order signatures
  88. - βœ… **Auto-reconnect WebSockets** - Resilient real-time connections
  89. - βœ… **Comprehensive Error Handling** - User-friendly error messages
  90. - βœ… **No Mocks** - Real Polymarket API integration throughout
  91. - βœ… **Full Test Coverage** - Production-grade testing with real APIs
  92. ---
  93. ## 🌐 Web Dashboard
  94. **NEW**: Manage and monitor your Polymarket MCP Server with a modern web interface!
  95. ```bash
  96. # Start the web dashboard
  97. polymarket-web
  98. # Or use the quick start script
  99. ./start_web_dashboard.sh
  100. ```
  101. Access at: **http://localhost:8080**
  102. ### Dashboard Features
  103. - **Real-time Monitoring**: Live MCP status, WebSocket connection, and statistics
  104. - **Configuration Management**: Visual sliders for safety limits and trading controls
  105. - **Market Discovery**: Search, filter, and browse markets with live updates
  106. - **Market Analysis**: AI-powered analysis with recommendations and risk assessment
  107. - **System Monitoring**: Performance charts, rate limits, and activity logs
  108. - **Dark Theme**: Professional UI optimized for extended use
  109. See [WEB_DASHBOARD.md](WEB_DASHBOARD.md) for complete documentation.
  110. ---
  111. ## πŸš€ Quick Start
  112. ### One-Command Installation (Recommended)
  113. **Try DEMO mode first** (no wallet needed):
  114. ```bash
  115. # macOS/Linux
  116. curl -sSL https://raw.githubusercontent.com/caiovicentino/polymarket-mcp-server/main/quickstart.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 150 on GitHub
  117. # Or clone and run locally
  118. git clone https://github.com/caiovicentino/polymarket-mcp-server.git
  119. cd polymarket-mcp-server
  120. ./quickstart.sh
  121. ```
  122. **Full installation** (with trading):
  123. ```bash
  124. # macOS/Linux
  125. ./install.sh
  126. # Windows
  127. install.bat
  128. ```
  129. The automated installer will:
  130. - βœ“ Check Python version (3.10+)
  131. - βœ“ Create virtual environment
  132. - βœ“ Install all dependencies
  133. - βœ“ Configure environment
  134. - βœ“ Set up Claude Desktop integration
  135. - βœ“ Test the installation
  136. ### Installation Options
  137. | Method | Command | Best For |
  138. |--------|---------|----------|
  139. | **Quick Start** | `./quickstart.sh` | First-time users, testing |
  140. | **DEMO Mode** | `./install.sh --demo` | No wallet, read-only access |
  141. | **Full Install** | `./install.sh` | Production trading setup |
  142. | **Windows** | `install.bat` | Windows users |
  143. ### DEMO Mode vs Full Mode
  144. **DEMO Mode** (No wallet required):
  145. - βœ… Market discovery and search
  146. - βœ… Real-time market analysis
  147. - βœ… AI-powered insights
  148. - βœ… Price monitoring
  149. - ❌ Trading disabled (read-only)
  150. **Full Mode** (Requires Polygon wallet):
  151. - βœ… Everything in DEMO mode
  152. - βœ… Place orders and execute trades
  153. - βœ… Portfolio management
  154. - βœ… Position tracking
  155. - βœ… Real-time trade notifications
  156. ### Manual Installation
  157. If you prefer manual setup:
  158. ```bash
  159. # Clone the repository
  160. git clone https://github.com/caiovicentino/polymarket-mcp-server.git
  161. cd polymarket-mcp-server
  162. # Create virtual environment
  163. python -m venv venv
  164. source venv/bin/activate # On Windows: venv\Scripts\activate
  165. # Install the package
  166. pip install -e .
  167. ```
  168. ### Configuration
  169. **Option 1: DEMO Mode** (easiest)
  170. ```bash
  171. cp .env.example .env
  172. # Edit .env and set:
  173. DEMO_MODE=true
  174. ```
  175. **Option 2: Full Trading Mode**
  176. ```bash
  177. cp .env.example .env
  178. # Edit with your Polygon wallet credentials
  179. nano .env
  180. ```
  181. **Required credentials (Full Mode):**
  182. ```env
  183. POLYGON_PRIVATE_KEY=your_private_key_without_0x_prefix
  184. POLYGON_ADDRESS=0xYourPolygonAddress
  185. ```
  186. **Recommended Safety Limits:**
  187. ```env
  188. MAX_ORDER_SIZE_USD=1000
  189. MAX_TOTAL_EXPOSURE_USD=5000
  190. MAX_POSITION_SIZE_PER_MARKET=2000
  191. MIN_LIQUIDITY_REQUIRED=10000
  192. MAX_SPREAD_TOLERANCE=0.05
  193. ENABLE_AUTONOMOUS_TRADING=false
  194. REQUIRE_CONFIRMATION_ABOVE_USD=500
  195. ```
  196. With `ENABLE_AUTONOMOUS_TRADING=false` (the default), every order is held and
  197. returned as `confirmation_required` until you re-issue it with `confirm=true`.
  198. Set it to `true` to let orders under `REQUIRE_CONFIRMATION_ABOVE_USD` go through
  199. without that step.
  200. ### Claude Desktop Integration
  201. Add to your Claude Desktop configuration file:
  202. **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
  203. **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
  204. ```json
  205. {
  206. "mcpServers": {
  207. "polymarket": {
  208. "command": "/path/to/your/venv/bin/python",
  209. "args": ["-m", "polymarket_mcp.server"],
  210. "cwd": "/path/to/polymarket-mcp-server",
  211. "env": {
  212. "POLYGON_PRIVATE_KEY": "your_private_key",
  213. "POLYGON_ADDRESS": "0xYourAddress"
  214. }
  215. }
  216. }
  217. }
  218. ```
  219. **Restart Claude Desktop** and you're ready to trade! πŸŽ‰
  220. ---
  221. ## πŸ“– Documentation
  222. ### Getting Started
  223. - **[Visual Installation Guide](VISUAL_INSTALL_GUIDE.md)** - Step-by-step with diagrams and screenshots
  224. - **[FAQ](FAQ.md)** - Frequently asked questions and troubleshooting
  225. - **[Setup Guide](SETUP_GUIDE.md)** - Detailed configuration instructions
  226. - **[Demo Video Script](DEMO_VIDEO_SCRIPT.md)** - Video tutorial scripts
  227. ### Developer Resources
  228. - **[Tools Reference](TOOLS_REFERENCE.md)** - Complete API documentation for all 45 tools
  229. - **[Agent Integration Guide](AGENT_INTEGRATION_GUIDE.md)** - How to integrate with your agents
  230. - **[Trading Architecture](TRADING_ARCHITECTURE.md)** - System design and architecture
  231. - **[WebSocket Integration](WEBSOCKET_INTEGRATION.md)** - Real-time data setup
  232. ### Examples & Guides
  233. - **[Usage Examples](USAGE_EXAMPLES.py)** - Code examples for all tools
  234. - **[Test Examples](TEST_EXAMPLES.py)** - Example test implementations
  235. - **[Market Analysis Scripts](analyze_top_markets.py)** - Advanced analysis examples
  236. ### System Architecture
  237. ```
  238. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  239. β”‚ POLYMARKET MCP SERVER β”‚
  240. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  241. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  242. β”‚ Claude β”‚
  243. β”‚ Desktop β”‚ (Natural language interface)
  244. β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜
  245. β”‚ MCP Protocol
  246. β–Ό
  247. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  248. β”‚ MCP Server (Python) β”‚
  249. β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
  250. β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
  251. β”‚ β”‚ Market β”‚ β”‚ Trading β”‚ β”‚
  252. β”‚ β”‚ Discovery β”‚ β”‚ Engine β”‚ β”‚
  253. β”‚ β”‚ (8 tools) β”‚ β”‚ (12 tools) β”‚ β”‚
  254. β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
  255. β”‚ β”‚
  256. β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
  257. β”‚ β”‚ Market β”‚ β”‚ Portfolio β”‚ β”‚
  258. β”‚ β”‚ Analysis β”‚ β”‚ Manager β”‚ β”‚
  259. β”‚ β”‚ (10 tools)β”‚ β”‚ (8 tools) β”‚ β”‚
  260. β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
  261. β”‚ β”‚
  262. β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
  263. β”‚ β”‚ Real-time WebSocket (7 tools) β”‚ β”‚
  264. β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
  265. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  266. β”‚
  267. β–Ό
  268. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  269. β”‚ Polymarket Infrastructure β”‚
  270. β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
  271. β”‚ β€’ CLOB API (Order placement & management) β”‚
  272. β”‚ β€’ Gamma API (Market data & analytics) β”‚
  273. β”‚ β€’ WebSocket (Real-time price feeds) β”‚
  274. β”‚ β€’ Polygon Chain (Settlement & execution) β”‚
  275. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  276. ```
  277. ---
  278. ## πŸ’‘ Usage Examples
  279. ### Market Discovery
  280. Ask Claude:
  281. ```
  282. "Show me the top 10 trending markets on Polymarket in the last 24 hours"
  283. "Find all crypto markets about Bitcoin"
  284. "What sports markets are closing in the next 12 hours?"
  285. "Search for markets about Trump"
  286. ```
  287. ### Market Analysis
  288. ```
  289. "Analyze the trading opportunity for the government shutdown market"
  290. "Compare these three markets and tell me which has the best risk/reward"
  291. "What's the current spread on the Eagles vs Packers market?"
  292. "Show me the orderbook depth for token ID xyz"
  293. ```
  294. ### Autonomous Trading
  295. ```
  296. "Buy $100 of YES tokens in [market_id] at $0.65"
  297. "Place a limit order: sell 200 NO at $0.40 in [market]"
  298. "Execute a smart trade: buy YES up to $500 in [market] using best strategy"
  299. "Cancel all my open orders in the government shutdown market"
  300. "Rebalance my position in [market] to $1000 with max 2% slippage"
  301. ```
  302. ### Portfolio Management
  303. ```
  304. "Show me all my current positions"
  305. "What's my total portfolio value?"
  306. "Analyze my portfolio risk and suggest improvements"
  307. "What's my P&L for the last 30 days?"
  308. "Which are my best and worst performing markets?"
  309. "Suggest portfolio optimizations for a conservative strategy"
  310. ```
  311. ### Real-time Monitoring
  312. ```
  313. "Subscribe to price changes for the government shutdown markets"
  314. "Monitor my order status in real-time"
  315. "Alert me when the Eagles vs Packers market moves more than 10%"
  316. "Show me real-time orderbook updates for [token_id]"
  317. ```
  318. ---
  319. ## πŸ§ͺ Testing
  320. ```bash
  321. # Install dev dependencies
  322. pip install -e ".[dev]"
  323. # Run all tests
  324. pytest
  325. # Run specific test suite
  326. pytest tests/test_trading_tools.py -v
  327. # Run with coverage
  328. pytest --cov=polymarket_mcp --cov-report=html
  329. # Run market analysis demo
  330. python demo_mcp_tools.py
  331. ```
  332. **Note:** All tests use real Polymarket APIs - NO MOCKS!
  333. ---
  334. ## πŸ›‘οΈ Safety & Security
  335. ### ⚠️ Important Security Considerations
  336. - **Private Key Protection**: Never share or commit your private key
  337. - **Start Small**: Begin with small amounts ($50-100) to test
  338. - **Understand Markets**: Only trade in markets you understand
  339. - **Monitor Positions**: Check your positions regularly
  340. - **Use Safety Limits**: Configure appropriate limits for your risk tolerance
  341. - **Never Risk More**: Than you can afford to lose
  342. ### Default Safety Limits
  343. ```env
  344. MAX_ORDER_SIZE_USD=1000 # Maximum $1,000 per order
  345. MAX_TOTAL_EXPOSURE_USD=5000 # Maximum $5,000 total exposure
  346. MAX_POSITION_SIZE_PER_MARKET=2000 # Maximum $2,000 per market
  347. MIN_LIQUIDITY_REQUIRED=10000 # Minimum $10,000 market liquidity
  348. MAX_SPREAD_TOLERANCE=0.05 # Maximum 5% spread
  349. ENABLE_AUTONOMOUS_TRADING=false # Every order needs confirm=true
  350. REQUIRE_CONFIRMATION_ABOVE_USD=500 # When autonomous: confirm orders over $500
  351. ```
  352. These can be customized in your `.env` file or Claude Desktop config.
  353. ### Choosing the Outcome
  354. Order tools take an `outcome` argument (`"Yes"`, `"No"`, or a label like
  355. `"Lakers"`). On a Yes/No market it defaults to `Yes`. Sports and multi-outcome
  356. markets have no Yes/No side, so the outcome must be given explicitly β€” the tool
  357. refuses the order and lists the available outcomes rather than guessing a side.
  358. ---
  359. ## 🀝 Contributing
  360. Contributions are welcome! We appreciate your help making this project better.
  361. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on:
  362. - How to report bugs
  363. - How to suggest features
  364. - Code standards and guidelines
  365. - Pull request process
  366. ### Quick Contribution Guide
  367. 1. Fork the repository
  368. 2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
  369. 3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
  370. 4. Push to the branch (`git push origin feature/AmazingFeature`)
  371. 5. Open a Pull Request
  372. ---
  373. ## πŸ“Š Project Stats
  374. - **Lines of Code**: ~10,000+ (Python)
  375. - **Tools**: 45 comprehensive tools
  376. - **Test Coverage**: High (real API integration)
  377. - **Documentation**: Comprehensive (multiple guides)
  378. - **Dependencies**: Modern Python packages (MCP, httpx, websockets, eth-account)
  379. ---
  380. ## 🌐 Community
  381. ### Join Our Communities
  382. - 🌾 **[Yield Hacker](https://opensea.io/collection/yield-hacker-pass-yhp)** - DeFi Innovation & Yield Farming
  383. - πŸ’° **[Renda Cripto](https://rendacripto.com.br/)** - Crypto Trading & Investments
  384. - πŸ—οΈ **[Cultura Builder](https://culturabuilder.com/)** - Builder Culture & Development
  385. ### Featured In
  386. - **[Awesome Agent Trading](https://github.com/laplace0x/awesome-agent-trading)** - Curated directory of AI trading agents, MCP servers, and prediction market tools
  387. ### Get Support
  388. - **GitHub Issues**: [Report bugs or request features](https://github.com/caiovicentino/polymarket-mcp-server/issues)
  389. - **GitHub Discussions**: [Ask questions and share ideas](https://github.com/caiovicentino/polymarket-mcp-server/discussions)
  390. - **Telegram Communities**: Get help from the community
  391. ---
  392. ## πŸ“„ License
  393. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  394. ---
  395. ## πŸ™ Acknowledgments
  396. This project was made possible by:
  397. - **Caio Vicentino** - Creator and lead developer
  398. - **Yield Hacker Community** - DeFi expertise and testing
  399. - **Renda Cripto Community** - Trading insights and validation
  400. - **Cultura Builder Community** - Builder culture and support
  401. - **[Polymarket](https://polymarket.com)** - Amazing prediction market platform
  402. - **[Anthropic](https://anthropic.com)** - Claude and the MCP protocol
  403. - **[py-clob-client](https://github.com/Polymarket/py-clob-client)** - Official Polymarket SDK
  404. Special thanks to all contributors and community members who have helped improve this project!
  405. ---
  406. ## ⚠️ Disclaimer
  407. This software is provided for educational and research purposes. Trading prediction markets involves financial risk.
  408. **Important Reminders:**
  409. - Cryptocurrency trading carries significant risk
  410. - Only invest what you can afford to lose
  411. - Past performance does not guarantee future results
  412. - This is not financial advice
  413. - Always do your own research (DYOR)
  414. - Start with small amounts to learn the system
  415. - Understand the markets you're trading
  416. - Monitor your positions regularly
  417. The authors and contributors are not responsible for any financial losses incurred through the use of this software.
  418. ---
  419. ## πŸ”— Links
  420. - **GitHub Repository**: [github.com/caiovicentino/polymarket-mcp-server](https://github.com/caiovicentino/polymarket-mcp-server)
  421. - **Polymarket**: [polymarket.com](https://polymarket.com)
  422. - **Polymarket Docs**: [docs.polymarket.com](https://docs.polymarket.com)
  423. - **MCP Protocol**: [modelcontextprotocol.io](https://modelcontextprotocol.io)
  424. - **Claude Code**: [claude.ai/code](https://claude.ai/code)
  425. ---
  426. ## πŸ“ˆ Roadmap
  427. ### Current Version (v0.1.0)
  428. - βœ… 45 comprehensive tools
  429. - βœ… Real-time WebSocket monitoring
  430. - βœ… Safety limits and risk management
  431. - βœ… Complete test suite
  432. - βœ… Comprehensive documentation
  433. ### Planned Features
  434. - [ ] CI/CD pipeline (GitHub Actions)
  435. - [ ] Enhanced AI analysis tools
  436. - [ ] Portfolio strategy templates
  437. - [ ] Market alerts and notifications
  438. - [ ] Performance analytics dashboard
  439. - [ ] Multi-wallet support
  440. - [ ] Advanced order types
  441. - [ ] Historical backtesting
  442. ---
  443. ## 🌟 Contributors
  444. Thanks to everyone who has contributed to this project!
  445. [![Contributors](https://contrib.rocks/image?repo=caiovicentino/polymarket-mcp-server)](https://github.com/caiovicentino/polymarket-mcp-server/graphs/contributors)
  446. ---
  447. <div align="center">
  448. **Built with ❀️ for autonomous AI trading on Polymarket**
  449. *Ready to make Claude your personal prediction market trader!* πŸš€
  450. [⭐ Star this repo](https://github.com/caiovicentino/polymarket-mcp-server) | [πŸ› Report Bug](https://github.com/caiovicentino/polymarket-mcp-server/issues) | [✨ Request Feature](https://github.com/caiovicentino/polymarket-mcp-server/issues)
  451. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.