Public.com交易MCP服务器

Public.com MCP Server

An MCP (Model Context Protocol) server that connects AI assistants to your Public.com brokerage account. Trade stocks, options, and crypto — get quotes, manage orders, and view your portfolio — all through natural language.

Disclaimer: For illustrative and informational purposes only. Not investment advice or recommendations. Use at your own risk.

Tools

Read-Only

Write (Destructive)

Bracket orders

place_order places a bracket by setting order_class to BRACKET, OCO or OTO and supplying at least one exit leg:

The exit legs are submitted automatically when the entry order fills, and every leg of the bracket — the entry included — reports the entry's order ID as its bracketId, so get_orders groups them.

The API accepts brackets for EQUITY and OPTION only; they need a whole-share quantity (not amount), must use the CORE market session, and the entry order_type must be LIMIT or MARKET (LIMIT only for OCO). preflight_order validates the entry order only — it has no view of the exit legs.

Order history

get_orders lists only the open/active orders in the portfolio snapshot. For everything else use the order-history tools:

Both are limited by the API to orders created within the last 30 days, and search_orders returns at most 500 orders. Each order includes trades (the individual fills), filledAt, replacedAt, lastModified and equityMarketSession. Note that equityMarketSession uses REGULAR / REST_OF_DAY / TWENTY_FOUR_HOURS, which is not the CORE / EXTENDED / TWENTY_FOUR_HOURS vocabulary that place_order's equity_market_session argument takes.

Event contracts

Browse event contracts (prediction markets) with get_event_categories → get_event_summary (page with next_token) → get_event_details, and chart with get_event_contract_bars. Prices are dollars from 0.00 to 1.00 and equal the implied probability. EventSummary.symbols lists related instruments (e.g. BTC-CRYPTO), not the event's contracts — those come from get_event_details. Outcome ids carry no exchange prefix (e.g. KXBALANCESHEET-EO26-6.6).

Trading recurring markets

For a recurring market such as the 15-minute "Up or Down" windows:

1. get_current_event(series="KXBTC15M") — the window open right now (series is the series ticker, shown on every get_event_summary / get_event_details result). Pass wait_seconds (≤ 120) to wait between windows.
2. get_event_details(event_symbol) — the YES/NO contracts, their asks, and whether the outcome is tradable and how many secondsLeft.
3. preflight_buy_event_contract → buy_event_contract(contract_symbol, quantity, limit_price) — a DAY limit buy. Omit limit_price and pass event_symbol to buy at the current ask, rounded up to a whole cent. Quantities take at most 2 decimals.
4. wait_for_settlement(event_symbol, contract_symbol=...) — waits up to 120 s per call and reports winner and won; on timeout it returns "status": "pending", so call again.

The two halves take different identifiers, and the API rejects the wrong one:

EVENTCONTRACT is also accepted as an instrument type by get_quotes, get_price_history, get_instrument, get_all_instruments and search_orders.

Prerequisites

• Python 3.10+
• Public.com account — Sign up
• Public.com API key — Get one here

Installation

pip install publicdotcom-mcp-server

Or install from source:

git clone https://github.com/publicdotcom/publicdotcom-mcp-server.git
cd publicdotcom-mcp-server
pip install .

Configuration

Set your API credentials as environment variables:

# Required
export PUBLIC_COM_SECRET=your_api_secret_key

# Optional — sets a default account so you don't need to specify it each time
export PUBLIC_COM_ACCOUNT_ID=your_account_id

Usage

Claude Desktop

Add this to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "public-com": {
      "command": "publicdotcom-mcp-server",
      "env": {
        "PUBLIC_COM_SECRET": "your_api_secret_key",
        "PUBLIC_COM_ACCOUNT_ID": "your_account_id"
      }
    }
  }
}

Claude Desktop (using uvx)

If you prefer using uvx (no pre-install needed):

{
  "mcpServers": {
    "public-com": {
      "command": "uvx",
      "args": ["publicdotcom-mcp-server"],
      "env": {
        "PUBLIC_COM_SECRET": "your_api_secret_key",
        "PUBLIC_COM_ACCOUNT_ID": "your_account_id"
      }
    }
  }
}

Running Directly

# stdio transport (default — for Claude Desktop, Claude Code, etc.)
publicdotcom-mcp-server

# Or run as a Python module
python -m publicdotcom_mcp_server

Hosted / Remote Deployment

For remote deployments (behind a reverse proxy or load balancer), switch to the streamable-HTTP transport:

export MCP_TRANSPORT=streamable-http
export PUBLIC_COM_SECRET=your_api_secret_key
export PORT=8000  # optional, defaults to 8000
export HOST=0.0.0.0  # optional, defaults to 0.0.0.0
publicdotcom-mcp-server

In this mode the server listens for MCP requests at POST /mcp. Clients authenticate per-request via an Authorization: Bearer <key> header, which takes priority over the PUBLIC_COM_SECRET environment variable — useful for multi-tenant deployments.

Testing with MCP Inspector

npx @modelcontextprotocol/inspector publicdotcom-mcp-server

Development

# Clone and install in development mode
git clone https://github.com/publicdotcom/publicdotcom-mcp-server.git
cd publicdotcom-mcp-server
pip install -e ".[dev]"

# Run tests
pytest

# Run the server locally
python -m publicdotcom_mcp_server

CI & Releases

• CI (.github/workflows/ci.yml) runs the test suite (Python 3.10–3.13) and ruff on every push to main and every pull request.
• Releases (.github/workflows/release.yml) run on every push to main. When the version in pyproject.toml is one that hasn't been released yet (no matching v<version> tag), the workflow builds the package, publishes to PyPI via Trusted Publishing (OIDC) — no API token is stored — and creates the corresponding GitHub Release. Merges that don't change the version are no-ops.

To cut a release: bump version in pyproject.toml in your PR and merge it to main. The release + PyPI publish + v<version> tag/GitHub Release happen automatically. One-time setup on PyPI (project → Publishing) must register a Trusted Publisher for this repo with workflow release.yml and environment pypi.

How It Works

This server wraps the publicdotcom-py Python SDK, exposing each API operation as an MCP tool. The MCP protocol allows AI clients to discover and call these tools through a standardized interface.

AI Client (Claude, etc.)
    ↕ MCP Protocol (stdio)
Public.com MCP Server
    ↕ HTTPS
Public.com Trading API

All tools include proper MCP tool annotations:

• Read-only tools are marked with readOnlyHint: true
• Order-placement tools are marked with readOnlyHint: false (they modify account state)
• Order cancellation tools (cancel_order, cancel_and_replace_order) are additionally marked with destructiveHint: true

License

Apache 2.0