kalshi-mcp-server

An mcp server that allows AI to operate on the prediction market, Kalshi

Implemented Tools

• get_tags_for_series_categories
  • Calls Kalshi public endpoint: GET /search/tags_by_categories
  • No API key required
• get_balance
  • Calls Kalshi private endpoint: GET /portfolio/balance
  • Requires API key authentication (KALSHI_API_KEY_ID + KALSHI_API_KEY_PATH)
• get_subaccount_balances
  • Calls Kalshi private endpoint: GET /portfolio/subaccounts/balances
  • Requires API key authentication (KALSHI_API_KEY_ID + KALSHI_API_KEY_PATH)
• create_subaccount
  • Calls Kalshi private endpoint: POST /portfolio/subaccounts
  • No arguments
  • Creates a new subaccount (maximum 32 per user)
  • Returns: subaccount_number (int, 1-32)
  • Requires API key authentication (KALSHI_API_KEY_ID + KALSHI_API_KEY_PATH)
• get_orders
  • Calls Kalshi private endpoint: GET /portfolio/orders
  • Optional arguments:
    • ticker (string; market ticker)
    • event_ticker (string; comma-separated event tickers, maximum 10)
    • status (string: resting|canceled|executed)
    • min_ts/max_ts (int; unix seconds)
    • limit (int, 1-200)
    • cursor (string)
    • subaccount (int, 0-32)
  • Returns portfolio orders (and optional pagination cursor)
  • Requires API key authentication (KALSHI_API_KEY_ID + KALSHI_API_KEY_PATH)
• get_order
  • Calls Kalshi private endpoint: GET /portfolio/orders/{order_id}
  • Required arguments:
    • order_id (string; the order identifier)
  • Returns a single order object with all order fields
  • Requires API key authentication (KALSHI_API_KEY_ID + KALSHI_API_KEY_PATH)
• create_order
  • Calls Kalshi private endpoint: POST /portfolio/orders
  • Required arguments:
    • ticker (string; market ticker)
    • side (string: yes|no)
    • action (string: buy|sell)
  • Optional arguments:
    • client_order_id (string; caller-specified order ID)
    • count (int, >=1; contract quantity)
    • count_fp (string; fixed-point contract count)
    • yes_price (int, 1-99; price in cents)
    • no_price (int, 1-99; price in cents)
    • yes_price_dollars (string; yes price in dollars)
    • no_price_dollars (string; no price in dollars)
    • expiration_ts (int; unix timestamp for order expiry)
    • time_in_force (string: fill_or_kill|good_till_canceled|immediate_or_cancel)
    • buy_max_cost (int; maximum cost in cents)
    • sell_position_floor (int; deprecated, only 0 allowed if set)
    • post_only (boolean)
    • reduce_only (boolean)
    • self_trade_prevention_type (string: taker_at_cross|maker)
    • order_group_id (string)
    • cancel_order_on_pause (boolean)
    • subaccount (int, 0-32)
  • Returns created order details
  • Requires API key authentication (KALSHI_API_KEY_ID + KALSHI_API_KEY_PATH)
• cancel_order
  • Calls Kalshi private endpoint: DELETE /portfolio/orders/{order_id}
  • Required arguments:
    • order_id (string; the order identifier)
  • Optional arguments:
    • subaccount (int, 0-32)
  • Returns the cancelled order object and the number of contracts reduced (reduced_by, reduced_by_fp)
  • Requires API key authentication (KALSHI_API_KEY_ID + KALSHI_API_KEY_PATH)
• get_positions
  • Calls Kalshi private endpoint: GET /portfolio/positions
  • Optional arguments:
    • cursor (string)
    • limit (int, 1-1000; defaults to 100)
    • count_filter (string; comma-separated from position and/or total_traded)
    • ticker (string; market ticker)
    • event_ticker (string; comma-separated event tickers, maximum 10)
    • subaccount (int, 0-32)
  • Returns portfolio positions with market_positions and event_positions arrays, plus pagination cursor
  • Requires API key authentication (KALSHI_API_KEY_ID + KALSHI_API_KEY_PATH)
• get_categories
  • Calls Kalshi public endpoint: GET /search/tags_by_categories
  • Returns only the category names
  • No API key required
• get_tags_for_series_category
  • Calls Kalshi public endpoint: GET /search/tags_by_categories
  • Requires one argument: category (exact category name)
  • Returns tags for the selected category
  • No API key required
• get_series_list
  • Calls Kalshi public endpoint: GET /series
  • Optional arguments:
    • category (string)
    • tags (string)
    • cursor (string)
    • limit (int, 1-1000)
    • include_product_metadata (boolean)
    • include_volume (boolean)
  • Returns typed series objects from Kalshi response
  • Logs warning/error details when response fields have unexpected types/shapes
  • No API key required
• get_series_tickers_for_category
  • Pages Kalshi public endpoint: GET /series
  • Required arguments:
    • category (string)
  • Optional arguments:
    • tags (string)
    • limit (int, 1-1000; defaults to 1000)
    • max_pages (int, 1-10000; defaults to 1000)
  • Returns only ticker values across all pages
  • No API key required
• get_markets
  • Calls Kalshi public endpoint: GET /markets
  • Optional arguments:
    • cursor (string)
    • limit (int, 1-1000)
    • status (string; Kalshi docs list values like unopened|open|paused|closed|settled)
    • tickers (string; comma-separated market tickers)
    • event_ticker (string; comma-separated event tickers)
    • series_ticker (string)
    • mve_filter (string: only|exclude)
    • min_created_ts/max_created_ts (int; unix seconds)
    • min_updated_ts (int; unix seconds)
    • min_close_ts/max_close_ts (int; unix seconds)
    • min_settled_ts/max_settled_ts (int; unix seconds)
  • Returns typed markets from Kalshi response
  • No API key required
• get_open_markets_for_series
  • Pages Kalshi public endpoint: GET /markets
  • Required arguments:
    • series_ticker (string)
  • Optional arguments:
    • limit (int, 1-1000; defaults to 1000)
    • max_pages (int, 1-10000; defaults to 1000)
  • Forces status=open and returns all markets across all pages
  • No API key required
• get_open_market_titles_for_series
  • Pages Kalshi public endpoint: GET /markets
  • Required arguments:
    • series_ticker (string)
  • Optional arguments:
    • limit (int, 1-1000; defaults to 1000)
    • max_pages (int, 1-10000; defaults to 1000)
  • Forces status=open and returns only ticker, title, subtitle, yes_sub_title, no_sub_title for each market across all pages
  • No API key required

Configuration

• KALSHI_API_BASE_URL
  • Default: https://api.elections.kalshi.com/trade-api/v2
• KALSHI_TIMEOUT_SECONDS
  • Default: 10
• KALSHI_API_KEY_ID
  • Required for authenticated/private endpoints (for example get_balance)
• KALSHI_API_KEY_PATH
  • Required for authenticated/private endpoints
  • Path to your Kalshi API private key PEM file
• .env
  • load_settings() reads a local .env file from the repo root and loads variables when they are not already set in the environment

Run as MCP stdio server

• Command (installed/editable):
  • python3 -m pip install -e .
  • python3 -m kalshi_mcp.server
• Command (no install):
  • PYTHONPATH=src python3 -m kalshi_mcp.server
• Transport:
  • JSON-RPC 2.0 over newline-delimited JSON on stdin/stdout

Development

• Run unit tests (unittest):
  • python3 -m unittest discover -s tests -p 'test_*.py'
• Run unit tests (pytest):
  • Install dev deps: python3 -m pip install -r requirements-dev.txt
  • Then: python3 -m pytest -q