# Public.com MCP Server [![License](https://img.shields.io/badge/license-Apache%202.0-green?style=flat-square)](LICENSE) [![Python](https://img.shields.io/badge/python-3.10%2B-blue?style=flat-square)](https://python.org) [![MCP](https://img.shields.io/badge/MCP-compatible-purple?style=flat-square)](https://modelcontextprotocol.io) An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that connects AI assistants to your [Public.com](https://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 | Tool | Description | |------|-------------| | `check_setup` | Verify API credentials and connectivity | | `get_accounts` | List all brokerage accounts | | `get_portfolio` | View positions, equity, buying power (including `dayTradeBuyingPower`), open orders | | `get_orders` | List active/open orders (bracket legs share a `bracketId`) | | `get_order` | Status and details of a specific order, including its fills (`trades` with each fill's venue MIC, `filledAt`, `replacedAt`, `lastModified`); last 30 days | | `search_orders` | Search order history — any status, last 30 days, up to 500 orders, filtered by status/side/symbols/type/time | | `get_history` | Transaction history (trades, deposits, dividends, etc.) | | `get_quotes` | Real-time quotes for stocks, crypto, options, event contracts | | `get_price_history` | OHLCV price history for equities, crypto, options, indices, or event contracts | | `get_instrument` | Details about a specific tradeable instrument | | `get_all_instruments` | List all available instruments with filters | | `search_bonds` | Filtered, paged search for fixed income instruments | | `get_bond_details` | Pricing, ratings, coupon and maturity info for a bond | | `get_option_expirations` | Available expiration dates for options | | `get_option_chain` | Full option chain (calls + puts) for a symbol | | `get_option_greeks` | Greeks (delta, gamma, theta, vega, rho, IV) for multiple options | | `get_option_greek` | Greeks for a single option symbol | | `get_tax_lots` | Unrealized tax-lot summary (per-lot gain/loss, term, cost basis) | | `get_tax_lots_for_symbol` | Unrealized tax-lot detail for a single symbol | | `get_tax_lots_csv` | Export unrealized tax lots as a Base64-encoded CSV file | | `get_strategy_quote` | Consolidated quote for a multi-leg option strategy | | `get_event_categories` | Event-contract (prediction market) categories, subcategories and frequency filters | | `get_event_summary` | Browse event contracts by category / symbol / frequency / resolution time, 100 per page | | `get_event_details` | One event's outcomes (with `floorStrike`), YES/NO contract prices, timeline and CFTC terms, plus per-outcome `tradable` / `secondsLeft` / `winner` | | `get_event_contract_bars` | Price-history bars for up to 8 contracts of one event | | `get_current_event` | The window of a recurring market (e.g. 15-minute `KXBTC15M`) trading right now; optional bounded wait | | `wait_for_settlement` | Wait (bounded) for an event outcome to settle and report the winning contract | | `preflight_order` | Estimate costs/impact before placing a single-leg order | | `preflight_multileg_order` | Estimate costs for multi-leg options strategies | | `preflight_short_order` | Estimate costs before placing a short-sale order | | `preflight_call_credit_spread` | Estimate costs for a Bear Call Spread | | `preflight_call_debit_spread` | Estimate costs for a Bull Call Spread | | `preflight_put_credit_spread` | Estimate costs for a Bull Put Spread | | `preflight_put_debit_spread` | Estimate costs for a Bear Put Spread | | `preflight_buy_event_contract` | Estimate costs before buying an event contract (YES or NO side) | ### Write (Destructive) | Tool | Description | |------|-------------| | `place_order` | Place a single-leg order (stocks, crypto, options), including market-on-close / limit-on-close; optionally a bracket order via `order_class` + exit-leg prices, or target specific tax lots via `tax_lot_matching_instructions` | | `place_multileg_order` | Place multi-leg orders (spreads, straddles, etc.) | | `place_call_credit_spread` | Place a Bear Call Spread | | `place_call_debit_spread` | Place a Bull Call Spread | | `place_put_credit_spread` | Place a Bull Put Spread | | `place_put_debit_spread` | Place a Bear Put Spread | | `place_short_order` | Place an equity short-sale order | | `buy_event_contract` | Buy an event contract (YES or NO side) with a DAY limit order, at the ask by default | | `flatten_and_go_short` | Sell an existing long position then go short (experimental) | | `cancel_order` | Cancel an existing order | | `cancel_and_replace_order` | Atomically cancel and replace an order | ### Order types `place_order`, `preflight_order`, `cancel_and_replace_order` and the short-sale tools take `order_type` as one of: | `order_type` | Price arguments | |------|-------------| | `MARKET` | none | | `LIMIT` | `limit_price` | | `STOP` | `stop_price` | | `STOP_LIMIT` | `stop_price` and `limit_price` | | `MARKET_ON_CLOSE` | none — executes at the closing auction | | `LIMIT_ON_CLOSE` | `limit_price` — executes at the closing auction | `place_order`, `preflight_order` and the short-sale tools also reject a price argument the order type doesn't take (e.g. `limit_price` on `MARKET_ON_CLOSE`). Bracket entries are `LIMIT` or `MARKET` only, and multi-leg orders are always `LIMIT`. ### Bracket orders `place_order` places a bracket by setting `order_class` to `BRACKET`, `OCO` or `OTO` and supplying at least one exit leg: | Argument | Meaning | |------|-------------| | `order_class` | `SIMPLE` (default, standalone) or `BRACKET` / `OCO` / `OTO` | | `take_profit_limit_price` | Limit price of the take-profit leg | | `stop_loss_stop_price` | Stop price of the stop-loss leg | | `stop_loss_limit_price` | Optional — makes the stop-loss a `STOP_LIMIT` rather than a `STOP` | 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: | Tool | Returns | |------|-------------| | `search_orders` | Orders in any status (filled, cancelled, rejected, …) matching optional `status`, `side`, `symbols` (`"SYMBOL"` or `"SYMBOL:TYPE"`), `security_type`, `open_close_indicator`, `created_after` / `created_before` filters | | `get_order` | One order by ID in the same shape | 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, each with the `marketIdentificationCode` — the ISO 10383 MIC of the execution venue, e.g. `XNAS` — when reported), `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: | Tools | Event identifier | Contract symbol | |------|-------------|-------------| | `get_event_summary`, `get_event_details`, `get_current_event`, `wait_for_settlement`, `*buy_event_contract` | `eventSymbol`, e.g. `KALSHI.KXBALANCESHEET-EO26` | e.g. `KALSHI.KXBALANCESHEET-EO26-6.6.Y` | | `get_event_contract_bars` | `-EVENT` id, e.g. `KALSHI.KXBALANCESHEET-EO26-EVENT` | `-EVENTCONTRACT` symbol, e.g. `KALSHI.KXBALANCESHEET-EO26-6.6.Y-EVENTCONTRACT` | `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](https://public.com/signup) - **Public.com API key** — [Get one here](https://public.com/settings/v2/api) ## Installation ```bash pip install publicdotcom-mcp-server ``` Or install from source: ```bash git clone https://github.com/publicdotcom/publicdotcom-mcp-server.git cd publicdotcom-mcp-server pip install . ``` ## Configuration Set your API credentials as environment variables: ```bash # 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): ```json { "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): ```json { "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 ```bash # 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: ```bash 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 ` header, which takes priority over the `PUBLIC_COM_SECRET` environment variable — useful for multi-tenant deployments. ### Testing with MCP Inspector ```bash npx @modelcontextprotocol/inspector publicdotcom-mcp-server ``` ## Development ```bash # 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` tag), the workflow builds the package, publishes to PyPI via [Trusted Publishing (OIDC)](https://docs.pypi.org/trusted-publishers/) — 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` 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`](https://pypi.org/project/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](https://modelcontextprotocol.io/docs/concepts/tools#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](LICENSE)