Polymarket MCP Server

How to use

You interact with the MCP server through a client interface (including the Claude Desktop integration or the web dashboard). Your goals are to discover markets, analyze opportunities, place and manage orders, and monitor your portfolio in real time. Rely on the built‑in safety limits to keep risk within your defined boundaries, and use the AI-powered insights to inform pricing and timing. You can subscribe to live price updates, watch order statuses, and receive trade alerts as events happen.

Typical usage patterns include: - Discover markets by keyword, category, or event, and monitor trending markets in real time. - Analyze markets with AI-assisted assessments of risk, reward, and opportunities, including cross-market comparisons. - Place orders with automated or manual controls, using limit or market orders, and rely on pre‑trade validations before execution. - Manage your portfolio with real-time position tracking, P&L, risk concentration analyses, and AI‑driven optimization suggestions. - Stay informed with live market updates, order statuses, and execution alerts delivered through the real-time monitor.

How to install

# One-command installation (Recommended)

# 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

If you prefer to install manually, follow these steps.

# 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 and running notes

Configure the server environment to enable production trading or DEMO access. You can switch between modes by setting environment variables in a dedicated .env file or through Claude Desktop integration.

# DEMO mode (easiest)
cp .env.example .env
# Edit .env and set:
DEMO_MODE=true

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

POLYGON_PRIVATE_KEY=your_private_key_without_0x_prefix
POLYGON_ADDRESS=0xYourPolygonAddress

# Recommended safety limits (example values)
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=true
REQUIRE_CONFIRMATION_ABOVE_USD=500

Claude Desktop Integration

To enable Claude to control the MCP Server from your desktop, add an MCP configuration entry to Claude Desktop.

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

Web dashboard and quick start

Access a modern web interface to manage and monitor the MCP Server. Start the dashboard and connect to the running server.

# Start the web dashboard
polymarket-web

# Or use the quick start script
./start_web_dashboard.sh

Access the dashboard at http://localhost:8080 and use real-time monitoring, configuration sliders for safety limits, and AI-powered market analysis from a single place.

Safety, security, and testing notes

Follow safety practices to protect private keys and manage risk. Begin with small allocations to learn the system and validate your setups with live data.

# Testing and validation (examples)
pip install -e ".[dev]"
pytest

Troubleshooting and notes

If you encounter connection issues, verify WebSocket stability, check environment variables, and confirm that necessary services are running in the expected paths.