Skip to content
Back to search

kalshi-quotes-mcp

Read-only Kalshi MCP server: batch quotes, precise prices, market rules, and order books. No API keys.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gordoaf--kalshi-quotes-mcp/badge.svg)](/listings/gordoaf--kalshi-quotes-mcp)

HTML

<a href="/listings/gordoaf--kalshi-quotes-mcp"><img src="/api/listings/gordoaf--kalshi-quotes-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 198 lines
  1. # Kalshi Quotes MCP
  2. [![CI](https://github.com/gordoaf/kalshi-quotes-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/gordoaf/kalshi-quotes-mcp/actions/workflows/ci.yml)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  4. **Give your AI assistant one reliable way to check Kalshi prices.** A small,
  5. read-only [Model Context Protocol](https://modelcontextprotocol.io/) server for
  6. batch quotes, market rules, and order books. No Kalshi account or API key required.
  7. ```mermaid
  8. flowchart LR
  9. A[ChatGPT / Claude / Gemini] -->|MCP| B[Kalshi Quotes MCP]
  10. B -->|Public HTTPS GET| C[Kalshi market data]
  11. ```
  12. - **Batch first:** up to 100 exact market tickers, normally one upstream request.
  13. - **Precise prices:** decimal strings in cents, including fractional cents and sizes.
  14. - **Honest snapshots:** missing liquidity, inactive markets, and retrieval times are explicit.
  15. - **Two transports:** local stdio and remote Streamable HTTP, using the official Python MCP SDK.
  16. - **Small scope:** four tools, no account access, trading operations, or price cache.
  17. ## Try it
  18. Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and
  19. [Git](https://git-scm.com/downloads), then run:
  20. ```sh
  21. uvx --from git+https://github.com/gordoaf/kalshi-quotes-mcp@v0.1.0 kalshi-quotes-mcp --check
  22. ```
  23. The live diagnostic discovers two open markets, checks batch quotes, market details,
  24. and an order book, then prints JSON. No credentials are involved. Python 3.11+ is
  25. required; uv can provision Python if needed.
  26. To work from a checkout:
  27. ```sh
  28. git clone https://github.com/gordoaf/kalshi-quotes-mcp.git
  29. cd kalshi-quotes-mcp
  30. uv sync --locked
  31. uv run kalshi-quotes-mcp --check
  32. ```
  33. Without uv, on **Windows PowerShell**:
  34. ```powershell
  35. git clone https://github.com/gordoaf/kalshi-quotes-mcp.git
  36. cd kalshi-quotes-mcp
  37. python -m venv .venv
  38. .\.venv\Scripts\python.exe -m pip install .
  39. .\.venv\Scripts\kalshi-quotes-mcp.exe --check
  40. ```
  41. On macOS/Linux use `.venv/bin/python` and `.venv/bin/kalshi-quotes-mcp` instead.
  42. ## Connect a client
  43. For clients accepting a local server definition:
  44. ```json
  45. {
  46. "mcpServers": {
  47. "kalshi-quotes": {
  48. "command": "uvx",
  49. "args": [
  50. "--from",
  51. "git+https://github.com/gordoaf/kalshi-quotes-mcp@v0.1.0",
  52. "kalshi-quotes-mcp"
  53. ]
  54. }
  55. }
  56. }
  57. ```
  58. Use the full path to `uvx` if your desktop app cannot find it. A client with a
  59. settings form takes the same command and separate arguments. You can also point
  60. it directly at the executable in your checkout's `.venv` with no arguments.
  61. | Client | Local installation | Shared remote server |
  62. | --- | --- | --- |
  63. | ChatGPT desktop | MCP server settings, stdio | Streamable HTTP |
  64. | Claude desktop | Desktop MCP configuration | Custom connector |
  65. | Gemini website | Cannot launch a local process | Custom app, eligible accounts |
  66. **A Git installation does not make localhost reachable from Gemini's website.**
  67. Use a publicly reachable HTTPS deployment or tunnel for remote clients. See
  68. [client setup and troubleshooting](docs/clients.md).
  69. Suggested project instruction:
  70. > For Kalshi price checks, use Kalshi Quotes MCP. Batch known tickers in one
  71. > get_quotes call. Report YES and NO bid/ask prices in cents and the retrieval
  72. > time. Last trade is historical. Report unavailable quotes and failures
  73. > explicitly. Do not substitute browser screenshots or remembered prices.
  74. ## Four tools
  75. | Tool | Use | Example arguments |
  76. | --- | --- | --- |
  77. | `get_quotes` | Batch prices for 1–100 exact tickers | `{"tickers":["YOUR-MARKET-TICKER"]}` |
  78. | `list_markets` | Discover a filtered page; not full-text search | `{"status":"open","limit":5}` |
  79. | `get_market` | One market's prices, status, and rules | `{"ticker":"YOUR-MARKET-TICKER"}` |
  80. | `get_orderbook` | Best-first bids, cheapest-first asks, sizes | `{"ticker":"YOUR-MARKET-TICKER","depth":10}` |
  81. Start with `list_markets`, then use the returned exact tickers. Titles, event
  82. tickers, and market tickers are different identifiers. `list_markets` accepts
  83. `series_ticker`, `event_ticker`, `status`, `limit` (1–100), and `cursor`. It defaults
  84. to open markets excluding combos; set `include_multivariate` to include them.
  85. Reuse the same filters with `next_cursor` to continue.
  86. ## Read the prices correctly
  87. - **Buy at ask; sell at bid.** Last trade is a separate historical observation.
  88. - Price strings are **cents per contract**: `"43.25"` means 43.25¢, or $0.4325.
  89. Quantities are decimal strings in contracts. No binary-float price arithmetic.
  90. - `null` is unavailable. Zero-size and 0/100¢ boundary quote values are suppressed
  91. conservatively; original upstream fields are retained as `raw_quote_fields`.
  92. - `quote_state` is `available`, `partial`, `empty`, or `inactive`. Nonactive
  93. markets can retain historical bid/ask values. Available does not guarantee a fill.
  94. - `last_trade_cents` is null when volume is zero. The API's last price does not
  95. supply an execution timestamp in this response.
  96. - `retrieved_at` records receipt of the response, **not** the exchange quote time.
  97. Upstream `Date`/`Age` headers are included when present. `market_updated_at` is
  98. upstream market metadata, not a guaranteed timestamp for each quote.
  99. - Each call fetches upstream; this server does not cache quotes. Kalshi may cache
  100. responses. Batch results are not a guaranteed atomic exchange snapshot.
  101. - Quotes exclude fees and depend on the available size. Book asks are derived from
  102. opposite-side bids: a 40¢ NO bid implies a 60¢ YES ask of the same size.
  103. Unknown tickers in a batch produce per-ticker `not_returned` errors without hiding
  104. valid results. This does not prove a ticker never existed: older markets may be
  105. archived. Order-book calls first confirm market existence, since Kalshi can return
  106. an empty book for an unknown ticker.
  107. ## Serve over HTTP
  108. ```sh
  109. kalshi-quotes-mcp --transport streamable-http --host 127.0.0.1 --port 8000
  110. ```
  111. Endpoint: `http://127.0.0.1:8000/mcp`. For a remote host behind an HTTPS proxy:
  112. ```sh
  113. kalshi-quotes-mcp --transport streamable-http --host 0.0.0.0 --port 8000 --allowed-host quotes.example.com
  114. ```
  115. Connect clients to `https://quotes.example.com/mcp`. Repeat `--allowed-host` for
  116. additional exact hostnames (optionally including a port). DNS rebinding protection
  117. stays enabled. This is a public-data server with **no built-in client authentication**;
  118. operators supply TLS, access restrictions if needed, ingress rate limits, and resource
  119. limits. A hostname allowlist is not authentication. Never expose a private trading bot
  120. through this endpoint.
  121. Upstream requests are pooled, limited to four concurrent requests, and paced at five
  122. requests per second **per process**. Adjust with `--requests-per-second` (maximum 20).
  123. Transient errors get at most three attempts within a 30-second request deadline;
  124. long `Retry-After` responses are surfaced rather than retried early. These are local
  125. controls, not a guarantee of any Kalshi rate allowance.
  126. ### Docker
  127. ```sh
  128. docker build -t kalshi-quotes-mcp .
  129. docker run --rm -p 127.0.0.1:8000:8000 kalshi-quotes-mcp
  130. ```
  131. For a public HTTPS proxy, append the HTTP flags including `--allowed-host` to
  132. `docker run`. The proxy must preserve an allowed Host header. The container runs
  133. as a non-root user. Docker is optional.
  134. ## Development
  135. ```sh
  136. uv sync --locked --group dev
  137. uv run pytest
  138. uv run ruff check .
  139. uv run ruff format --check .
  140. uv build
  141. ```
  142. Tests are offline and include MCP protocol calls over stdio and HTTP. `--check` is
  143. the separate live API diagnostic. See [contributing](CONTRIBUTING.md) and
  144. [security](SECURITY.md).
  145. ## Scope and sources
  146. This project reads public prediction-market data. It cannot read your positions or
  147. place, modify, or cancel orders. Kalshi's rate limits, availability, and terms apply;
  148. self-hosting removes a separate MCP provider's allowance, not exchange limits.
  149. - [Public market data](https://docs.kalshi.com/getting_started/quick_start_market_data)
  150. - [Markets API](https://docs.kalshi.com/api-reference/market/get-markets)
  151. - [Order-book semantics](https://docs.kalshi.com/getting_started/orderbook_responses)
  152. - [Official Python MCP SDK](https://py.sdk.modelcontextprotocol.io/)
  153. - [Kalshi's official hosted MCP](https://docs.kalshi.com/getting_started/mcp), an alternative
  154. if you prefer a provider-managed connector.
  155. Independent project, not affiliated with or endorsed by Kalshi. [MIT licensed](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.