How do I use kalshi-mcp-server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@kalshi-mcp-server what's the implied probability of a Fed rate cut in December?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

kalshi-mcp-server

by nexosdata

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

kalshi-mcp-server

License: MIT MCP Version Node.js Version Tests Runtime Dependencies

Production-ready Model Context Protocol (MCP) server for Kalshi CFTC-regulated prediction markets. Empowers Claude Desktop, Cursor IDE, Windsurf, and quantitative AI agents to query live Level 2 orderbook depth, calculate exact CFTC Rule 40.2 taker fees, solve quadratic arbitrage breakevens, calculate implied probabilities and scenario yields, and scan cross-venue pricing spreads against Polymarket.

Targeted Keywords & Highlights

kalshi mcp server – Native JSON-RPC 2.0 stdio transport adhering to MCP 2024-11-05.
model context protocol kalshi – Real-time event contracts: Fed funds rate cuts, CPI prints, S&P 500, weather, and presidential politics.
claude kalshi tool – Instant copy-paste Claude Desktop integration with one-click terminal launcher.
cursor kalshi mcp – Full IDE context for Cursor AI agents scanning prediction market microstructure.
cftc prediction market mcp – Exact regulatory clearing math with Rule 40.2 taker fees: $\lceil 0.07 \cdot C \cdot P \cdot (1 - P) \rceil$.

Related MCP server: Rekko MCP

Architecture Overview

flowchart TD
    subgraph Clients["Client Environments"]
        CD["Claude Desktop (macOS / Win / Linux)"]
        CU["Cursor IDE / Windsurf / VS Code"]
        AI["Autonomous AI Trading Agent"]
    end

    subgraph Server["kalshi-mcp-server (stdio JSON-RPC 2.0)"]
        TR["Transport Decoder<br/>(Newline-Delimited & Content-Length)"]
        RT["Router & MCP Dispatcher<br/>(Spec 2024-11-05)"]
        
        subgraph Tools["Tool Engine"]
            T1["kalshi_orderbook<br/>(L2 Depth & OBI)"]
            T2["kalshi_fee_calculator<br/>(CFTC Rule 40.2 & Quadratic Solver)"]
            T3["kalshi_market_search<br/>(Economics, Politics, Financials, Climate)"]
            T4["kalshi_implied_probability<br/>(Yields, Scenarios & Kelly Sizing)"]
            T5["kalshi_cross_spread<br/>(Kalshi vs Polymarket Box Spreads)"]
        end

        GW["NaxosData Gateway Client & Microstructure Provider"]
    end

    subgraph Liquidity["Prediction Market Liquidity"]
        ND["NaxosData Institutional API Gateway<br/>(api.naxosdata.com)"]
        PUB["Kalshi Public API v2<br/>(Direct Web Fallback)"]
        SIM["Normalized Microstructure Fallback Engine"]
    end

    CD -->|stdio JSON-RPC| TR
    CU -->|stdio JSON-RPC| TR
    AI -->|stdio JSON-RPC| TR

    TR --> RT
    RT --> T1
    RT --> T2
    RT --> T3
    RT --> T4
    RT --> T5

    T1 --> GW
    T2 --> GW
    T3 --> GW
    T4 --> GW
    T5 --> GW

    GW -->|Bearer Auth| ND
    GW -.->|Public HTTP| PUB
    GW -.->|Deterministic Offline| SIM

Available MCP Tools

Tool Name	Parameters	Description
`kalshi_orderbook`	`ticker` (req), `depth`	Fetches live Level 2 depth, bid/ask spread in cents, top-5 depth, and Order Book Imbalance (OBI) for Kalshi contracts.
`kalshi_fee_calculator`	`contracts`, `price`, `primary_price`, `target_roi_pct`, `primary_fee_cents`	Calculates statutory CFTC Rule 40.2 taker fees and solves closed-form quadratic breakeven prices for cross-venue arbitrage.
`kalshi_market_search`	`query`, `category`, `status`, `limit`	Searches Kalshi prediction markets across Economics, Politics, Financials, Climate, and Tech & Culture.
`kalshi_implied_probability`	`price` (req), `outcome`, `contracts`, `settlement_days`, `subjective_prob_pct`, `bankroll_usd`	Calculates market-implied probabilities, gross & net payout yields, scenario matrices, and Kelly criterion allocation.
`kalshi_cross_spread`	`ticker`, `category`, `min_net_roi_pct`, `limit`	Queries cross-venue price spreads and dual-leg arbitrage between Kalshi and Polymarket with exact fee deductions.

Quickstart

1. Instant Run via NPX

npx kalshi-mcp-server --help

2. Inspect Available Tools

npx kalshi-mcp-server --tools

3. Test an MCP Tool from CLI

# Level 2 orderbook for December 2026 Fed Funds Rate Cut
npx kalshi-mcp-server --test-call kalshi_orderbook '{"ticker":"FED-26DEC","depth":5}'

# Compute CFTC fees & solve quadratic breakeven against a 44¢ Polymarket leg
npx kalshi-mcp-server --test-call kalshi_fee_calculator '{"contracts":100,"price":52,"primary_price":44,"target_roi_pct":2.5}'

# Search active climate & weather contracts
npx kalshi-mcp-server --test-call kalshi_market_search '{"category":"Climate"}'

# Calculate implied probability and Kelly sizing for a 55¢ contract
npx kalshi-mcp-server --test-call kalshi_implied_probability '{"price":55,"settlement_days":45,"subjective_prob_pct":65,"bankroll_usd":25000}'

# Scan cross-venue spreads with Polymarket
npx kalshi-mcp-server --test-call kalshi_cross_spread '{"min_net_roi_pct":1.0}'

Configuration Guides

Claude Desktop Setup

Add the server definition to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "kalshi": {
      "command": "npx",
      "args": ["-y", "kalshi-mcp-server"],
      "env": {
        "NAXOS_API_KEY": "your_naxos_api_key_here",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Cursor IDE Setup

Add the server entry to .cursor/mcp.json in your project root or workspace:

{
  "mcpServers": {
    "kalshi": {
      "command": "npx",
      "args": ["-y", "kalshi-mcp-server"],
      "env": {
        "NAXOS_API_KEY": "your_naxos_api_key_here"
      }
    }
  }
}

Windsurf & Continue Setup

For Windsurf (~/.codeium/windsurf/mcp_config.json) or Continue (~/.continue/config.json):

{
  "mcpServers": [
    {
      "name": "kalshi",
      "command": "npx",
      "args": ["-y", "kalshi-mcp-server"],
      "env": {
        "NAXOS_API_KEY": "your_naxos_api_key_here"
      }
    }
  ]
}

Deep Dive: Tool Documentation & Usage

1. `kalshi_orderbook`

Fetches normalized Level 2 orderbook depth, bid/ask spread in cents, and Order Book Imbalance (OBI).

{
  "ticker": "FED-26DEC",
  "depth": 5
}

Key Response Fields:

best_bid_cents / best_ask_cents: Top of book quoted in integer cents ($0.01 - $0.99).
spread_cents: Tightness of the market in cents.
obi_top5: Order Book Imbalance across top-5 levels: $$\text{OBI} = \frac{V_{\text{bid}} - V_{\text{ask}}}{V_{\text{bid}} + V_{\text{ask}}}$$
top5_depth_contracts: Aggregated contract liquidity across top 5 price steps.
estimated_cftc_fee_cents: Statutory fee for a baseline order of 100 contracts at mid price.

2. `kalshi_fee_calculator`

Calculates statutory CFTC Rule 40.2 taker fees and solves closed-form quadratic breakeven prices for cross-venue matched trades.

{
  "contracts": 100,
  "price": 52,
  "primary_price": 44,
  "target_roi_pct": 2.5,
  "primary_fee_cents": 0.8
}

Statutory Regulatory Fee Schedule (CFTC Rule 40.2)

Kalshi operates as a Designated Contract Market (DCM) regulated by the US Commodity Futures Trading Commission (CFTC). The standard exchange taker fee formula is: $$\text{Fee} = \left\lceil 0.07 \cdot C \cdot P \cdot (1 - P) \right\rceil$$ Where:

$C$ is the number of event contracts.
$P$ is the contract price in dollars ($0.01 \le P \le 0.99$).
$\lceil \cdot \rceil$ is the ceiling operator rounding up to the nearest whole integer cent ($0.01) per trade order.

Quadratic Breakeven Formulation

When executing cross-venue matched pairs (e.g. Polymarket YES at price $P_1$ with fee $F_1$, paired with Kalshi NO at price $P_2$), achieving a target net return on investment $R$ requires: $$P_1 + \frac{F_1}{C} + P_2 + \frac{\text{Fee}_{\text{Kalshi}}(C, P_2)}{C} \le \frac{1}{1 + R}$$

Approximating the continuous fee bound yields the quadratic inequality: $$0.07 P_2^2 - 1.07 P_2 + K \ge 0$$ $$\text{where } K = \frac{1}{1 + R} - P_1 - \frac{F_1}{C}$$

The solver computes the analytic root $P_2^* = \frac{1.07 - \sqrt{1.1449 - 0.28 K}}{0.14}$ and verifies it against the discrete ceiling step-function.

3. `kalshi_market_search`

Discovers active and settled event contracts across Kalshi's institutional categories.

{
  "query": "CPI",
  "category": "Economics",
  "status": "ACTIVE",
  "limit": 5
}

Supported Categories:

Economics: Fed interest rates, CPI headline & core inflation, non-farm payrolls, GDP, recession.
Politics: Presidential elections, congressional control, approvals, judicial appointments.
Financials: S&P 500 year-end closes, Nasdaq 100, 10-Year Treasury Yields, commodity strikes.
Climate: Daily maximum temperatures (NYC, Miami, Chicago, Austin), snowfall records, hurricane landfalls.
Tech & Culture: Frontier AI benchmarks (ARC-AGI), spaceflight launches, regulatory actions.

4. `kalshi_implied_probability`

Transforms quoted market prices into probability distributions, scenario payoffs, and optimal bet sizing.

{
  "price": 55,
  "outcome": "YES",
  "contracts": 100,
  "settlement_days": 45,
  "subjective_prob_pct": 65,
  "bankroll_usd": 25000
}

Output Features:

Raw Implied Probability: Directly implied by the market price ($P \times 100$%, e.g., 0.62 = 62.0%).
Spread & Fee Adjusted Break-Even Win Rate: Minimum probability required to overcome CFTC Rule 40.2 taker drag.
Annualized APY Yield: Net holding yield annualized over event duration.
Kelly Criterion Optimal Sizing: $$f^* = \frac{b \cdot p - q}{b}$$ Recommends both full Kelly fraction and half-Kelly position sizing in USD to safeguard bankroll against downside variance.

5. `kalshi_cross_spread`

Scans matched events across Kalshi and Polymarket, identifying pricing discrepancies and net arbitrage edge.

{
  "category": "Economics",
  "min_net_roi_pct": 0.5,
  "limit": 10
}

Evaluation Pipeline:

Aligns dual-venue order books for equivalent resolution terms.
Evaluates dual-box legs:
- Strategy A: Buy Kalshi YES + Buy Polymarket NO.
- Strategy B: Buy Polymarket YES + Buy Kalshi NO.
Automatically deducts Kalshi Rule 40.2 taker fee and Polygon L2 order execution gas.
Assesses Oracle Resolution Divergence (e.g. Kalshi BLS / Fed statistical releases vs. Polymarket UMA Optimistic Oracle).

Environment Variables

Variable	Type	Default	Description
`NAXOS_API_KEY`	String	Optional	Your NaxosData API key (`nx_live_...` or `nx_pro_...`) for institutional Level 2 feeds.
`NAXOS_BASE_URL`	String	`https://api.naxosdata.com`	API Gateway endpoint.
`LOG_LEVEL`	String	`info`	Logging verbosity on STDERR (`debug`, `info`, `warn`, `error`).
`DEBUG`	Boolean	`false`	Enables full JSON-RPC payload logging on STDERR.

Local Development & Testing

This project has zero production runtime dependencies and uses Node.js native fetch and standard library streams.

# 1. Clone repository
git clone https://github.com/nexosdata/kalshi-mcp-server.git
cd kalshi-mcp-server

# 2. Install dev dependencies (TypeScript & @types/node)
npm install

# 3. Build TypeScript to dist/
npm run build

# 4. Run automated test suite (39 tests)
npm test

# 5. Typecheck
npm run typecheck

License

Available Tools

5 tools

kalshi_cross_spreadA

Queries live cross-venue spreads, pricing divergences, and dual-leg arbitrage opportunities between Kalshi and Polymarket contracts, with exact CFTC fee and Polygon gas deductions.

Name	Required	Description	Default
`limit`	No	Maximum number of matched pairs to return (default: 10, max: 50).
`ticker`	No	Kalshi market ticker to filter (e.g. 'FED-26DEC', 'CPI-26DEC', 'INX-26DEC', 'RECESS-26', 'HURR-26CAT4').
`category`	No	Filter by category (e.g. 'Economics', 'Financials', 'Climate', 'Politics', 'ALL').	ALL
`min_net_roi_pct`	No	Minimum net ROI percentage required after all fees and gas (default: 0.5%).

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the behavioral burden. It adds useful context by mentioning live data and exact CFTC fee and Polygon gas deductions, but it does not explicitly confirm read-only behavior, rate limits, authentication needs, data freshness, or whether any orders can be placed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single dense sentence with no wasted words, front-loading the primary purpose and then adding the fee/gas refinement. Every clause contributes to distinguishing the tool's output.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description still conveys the conceptual return values (spreads, divergences, arbitrage opportunities) and notes fee/gas deductions. It is nearly complete for selection and invocation, though it could say more about result shape or matching methodology.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds no parameter-specific meaning beyond what the schema provides, such as how ticker matching works or how category filtering interacts with min_net_roi_pct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Queries' and names the exact resource: live cross-venue spreads, pricing divergences, and dual-leg arbitrage opportunities between Kalshi and Polymarket contracts. Its cross-venue focus clearly distinguishes it from siblings like kalshi_orderbook and kalshi_fee_calculator.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this tool is for cross-venue arbitrage and spread analysis, but it does not explicitly state when to use it versus related tools such as kalshi_fee_calculator or kalshi_orderbook. There are no exclusions or alternative-routing instructions, leaving usage selection largely inferential.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

kalshi_fee_calculatorB

Calculates CFTC Rule 40.2 exchange taker fees for Kalshi contracts and solves closed-form quadratic breakeven prices for cross-venue arbitrage pairs.

Name	Required	Description
`price`	No	Kalshi contract price in cents (e.g. 52 for 52¢) or dollars (e.g. 0.52).
`contracts`	No	Number of binary event contracts to trade (default: 100).
`primary_price`	No	Optional counterpart leg price (e.g. Polymarket YES price in cents or dollars) to solve for the maximum Kalshi NO price that satisfies the target net ROI.
`target_roi_pct`	No	Target net return on investment percentage required after all exchange fees (default: 0.0%).
`primary_fee_cents`	No	Primary venue execution fee/gas in cents (default: 0.8¢ for Polygon PoS gas).

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the fee rule (CFTC Rule 40.2) and the closed-form quadratic breakeven method, but it does not state whether the tool is purely computational, what assumptions apply, or how errors or edge cases are handled.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no wasted clauses. It combines two related capabilities efficiently and avoids repetition of schema details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a five-parameter calculator with no annotations and no output schema, the description explains the broad purpose but not the shape or meaning of the returned results. The rich schema compensates for parameter documentation, but the description still leaves behavioral and output expectations partially inferred.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five parameters are already well documented in the schema. The description adds context about Kalshi contracts and arbitrage pairs but does not add parameter-level meaning beyond what the schema provides, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource: calculating Kalshi exchange taker fees under CFTC Rule 40.2, plus solving breakeven prices for cross-venue arbitrage. This is clear enough to distinguish from an orderbook or market-search sibling, but it does not explicitly name or contrast against any sibling tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the calculator is for fee and breakeven calculations, but it gives no explicit when-to-use guidance, prerequisites, or alternatives. An agent must infer the context from the functionality alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

kalshi_implied_probabilityB

Calculates market implied probability, gross & net payout yields, event scenario outcomes (YES win vs NO win), and Kelly criterion sizing for Kalshi contracts.

Name	Required	Description	Default
`price`	Yes	Kalshi contract market price in cents (e.g. 52 for 52¢) or dollars (e.g. 0.52).
`outcome`	No	Outcome side to analyze (default: 'YES').	YES
`contracts`	No	Number of contracts in hypothetical trade (default: 100).
`bankroll_usd`	No	Total bankroll in USD to calculate Kelly dollar allocation (default: $10,000).
`settlement_days`	No	Days remaining until market expiration/settlement to calculate annualized APY yield.
`subjective_prob_pct`	No	Your estimated subjective true probability in percentage (e.g. 60 for 60%) to compute edge, EV, and Kelly criterion allocation.

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full behavioral disclosure. The word 'Calculates' implies a read-only, side-effect-free operation, but the description does not explicitly state that there are no state changes, nor does it describe authentication needs or rate limits. It also does not specify the return format, though it lists several computed outputs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that lists the key calculations. There is no filler, and every item mentioned contributes to understanding what the tool returns. It is appropriately sized for a focused calculation tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does list the main returns (implied probability, yields, scenario outcomes, Kelly sizing), giving the agent a good sense of what to expect. The absence of annotations is partially offset by the 'Calculates' phrasing implying safety. Slightly more detail on return structure or edge-case behavior would make it fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already fully documents all six parameters. The description adds no parameter-level meaning beyond what the schema provides. A baseline score of 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb (calculates) and a detailed set of resources (market implied probability, payout yields, scenario outcomes, Kelly sizing), making the tool's purpose immediately clear. It does not explicitly differentiate itself from the sibling tools (orderbook, market_search, fee_calculator, cross_spread), but the unique analytical focus distinguishes it implicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives. The description states what it calculates but does not say the context in which an agent should invoke it, nor does it mention exclusions or prerequisites. Usage is only passively implied by the tool name and output list.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

kalshi_market_searchA

Searches Kalshi CFTC-regulated prediction markets by keywords, category (Economics, Politics, Financials, Climate, Tech & Culture), and status.

Name	Required	Description	Default
`limit`	No	Maximum number of markets to return (default: 10, max: 50).
`query`	No	Search query keyword (e.g. 'Fed', 'CPI', 'recession', 'temperature', 'S&P 500', 'election').
`status`	No	Filter by market status (default: 'ACTIVE').	ACTIVE
`category`	No	Filter by market category (default: 'ALL').	ALL

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

While there are no annotations, the description includes the crucial context that the markets are 'CFTC-regulated.' This adds a layer of compliance and risk context that goes beyond standard API functionality. However, it lacks operational details like rate limits or specific error behavior that would constitute full transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, highly efficient sentence that front-loads the core action ('Searches') followed immediately by the complete list of filtering mechanisms. There is zero wasted language.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The definition is complete for a simple search tool, clearly outlining the resource being searched and all available filters. It provides all the necessary information for an agent to determine if and how to call the tool based on a user request.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the schema coverage is 100%, the description adds semantic value by explicitly listing the specific categories (Economics, Politics, Financials, etc.) and noting the ability to search by 'keywords,' providing richer context for the `query` and `category` parameters than the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states its function is to search Kalshi prediction markets. Furthermore, by focusing on search criteria (keywords, category, status), it distinguishes itself from sibling tools like 'kalshi_orderbook' or 'kalshi_fee_calculator' which handle specific market interactions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides clear guidance on the inputs and types of data available for filtering (keywords, the six specific categories, and status). It implicitly guides usage by listing these specific options, ensuring the agent knows the boundaries of the search functionality.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

kalshi_orderbookB

Fetches live Level 2 orderbook depth, bid/ask spread in cents, top-5 depth, and Order Book Imbalance (OBI) for Kalshi CFTC-regulated contracts (Fed funds rates, CPI inflation, elections, weather).

Name	Required	Description	Default
`depth`	No	Number of price levels to return on bid and ask sides (default: 5, max: 50).
`ticker`	Yes	Kalshi market ticker/symbol (e.g. 'FED-26DEC', 'CPI-26DEC', 'INX-26DEC', 'RECESS-26', 'KXHIGHDCA-26DEC', 'PRES-2028-GOP').

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. 'Fetches live' implies a read-only, real-time operation and it lists the returned metrics, but it does not disclose authentication needs, rate limits, data freshness guarantees, or failure behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is a single front-loaded sentence with no redundant or filler content. Every phrase contributes to identifying the resource, the returned data, and the contract domain.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the main output components and contract universe, which helps since there is no output schema. However, it leaves gaps around output structure, interpretation of OBI, and when this tool is preferred over siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented. The description mentions depth and contract types but adds no parameter-level semantics beyond what the schema provides, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb, 'Fetches', and names the exact resource and returned metrics: Level 2 orderbook depth, bid/ask spread, top-5 depth, and OBI. It is clear what the tool does, though it does not explicitly differentiate itself from sibling tools such as kalshi_market_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no explicit guidance on when to use this tool versus alternatives like kalshi_market_search or kalshi_cross_spread. Usage is only implied by the purpose statement, and there are no exclusions or prerequisite conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

5 tool updatesv1.0.0Nov 1, 2026
- First observedkalshi_cross_spread
- First observedkalshi_fee_calculator
- First observedkalshi_implied_probability
- First observedkalshi_market_search
- First observedkalshi_orderbook

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored 2026-11-01 20:45 across 5 tools

Disambiguation4/5

Each tool targets a clearly different function: orderbook depth, market search, fee calculation, probability/Kelly analytics, and cross-venue arbitrage. There is minor conceptual overlap between fee/breakeven calculations and cross-spread arbitrage economics, but the descriptions make the boundaries mostly clear.

Naming Consistency5/5

All tools use a consistent kalshi_ prefix followed by a descriptive noun phrase. Although the names are noun-oriented rather than verb_noun, the convention is uniform and predictable across the entire set.

Tool Count5/5

Five tools is well within the ideal range for a focused analytics server. Each tool covers a distinct part of the Kalshi market-analysis workflow without unnecessary surface area.

Completeness4/5

The surface covers search, orderbook depth, fee modeling, implied probability/Kelly sizing, and cross-venue arbitrage, which are the core analytics for this domain. Minor gaps exist around fetching a single market by ticker or accessing historical price data, but the main workflows are supported.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Related MCP Connectors

EventTrader MCP B
com.cymetica
AI prediction market trading — real-time data, CLOB exchange, Prop Desk, 40+ tools
Finance Cryptocurrency Blockchain
1671
https://cymetica.com/mcp/v1
Mantis A
io.github.Alfred768
Cross-venue prediction market routing for AI agents with arbitrage, quotes, history, and signals.
Finance Cryptocurrency Autonomous Agents
62
https://mantiss.store/mcp
Prediction Market Intelligence A
markets.lacuna
Polymarket in your AI: market rules, real fill costs, who is trading, top traders. Read-only.
Finance Cryptocurrency Web3 & Decentralized Tech
71
https://mcp.lacuna.markets/mcp
MagicMarkets AOAuth
com.magicmarkets
Sports prediction markets for AI agents — live prices, quotes, orders, and positions.
Sports Finance
1
https://magicmarkets.com/mcp

Related MCP Servers

telekash-mcp-server
Finance Search Research & Data
TeleKashOracle
A
license
A
quality
D
maintenance
Prediction market probability oracle for AI agents. 26 tools across 500+ live markets from Kalshi and Polymarket. Cross-source arbitrage detection, structured TPF signals, Kelly Criterion sizing, agent performance tracking, and webhook alerts.
Updated 7 months ago (2026-03-19 16:13 UTC)
9
74 npm
1
MIT
Rekko MCP
Finance Search Research & Data
Rekko-AI
A
license
A
quality
D
maintenance
Provides prediction market intelligence, research, and strategy signals for platforms like Kalshi, Polymarket, and Robinhood. It enables AI assistants to perform market screening, arbitrage detection, and deep causal analysis to support informed trading decisions.
Updated 7 months ago (2026-04-07 22:09 UTC)
27
1
MIT
oddsrail
Finance Blockchain Cryptocurrency
hmesutozsoy
A
license
B
quality
A
maintenance
Enables MCP-compatible AI agents to research and trade prediction markets on Polymarket and Kalshi, including market search, orderbooks, price history, positions, order routing, and on-chain builder-code attribution, plus overshoot and dispute-risk signals.
Updated 4 days ago (2026-10-29 14:00 UTC)
42
69 PyPI
1
MIT
Problee MCPofficial
Autonomous Agents Finance Research & Data
pprotocol-us
A
license
B
quality
B
maintenance
Enables AI agents to discover and read live prediction markets with their prices, price history and recent trades, view the public leaderboard, and place or cancel limit orders while tracking their own positions. It also installs into Claude Desktop, Claude Code, Cursor or Codex using a local bridge that keeps the API key in a private credentials file instead of command-line arguments.
Updated a month ago (2026-10-02 21:54 UTC)
31
27 npm
MIT

kalshi-mcp-server

Targeted Keywords & Highlights

Architecture Overview

Available MCP Tools

Quickstart

1. Instant Run via NPX

2. Inspect Available Tools

3. Test an MCP Tool from CLI

Configuration Guides

Claude Desktop Setup

Cursor IDE Setup

Windsurf & Continue Setup

Deep Dive: Tool Documentation & Usage

1. kalshi_orderbook

2. kalshi_fee_calculator

Statutory Regulatory Fee Schedule (CFTC Rule 40.2)

Quadratic Breakeven Formulation

3. kalshi_market_search

4. kalshi_implied_probability

5. kalshi_cross_spread

Environment Variables

Local Development & Testing

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Problee MCPofficial

1. `kalshi_orderbook`

2. `kalshi_fee_calculator`

3. `kalshi_market_search`

4. `kalshi_implied_probability`

5. `kalshi_cross_spread`