MCP Server Kalshi

MCP Server Kalshi

一个 MCP 服务，可为 Claude Code 和其他 Agent 框架提供与 Kalshi 的一流接口。它专为端到端交易而打造：浏览市场、研究市场、阅读 确切的 结算规则 （包括获取合约条款 PDF），并通过 MCP 工具执行交易。

亮点

• 发现 — list_markets、get_market、list_events、get_event、list_series、 get_series。（Kalshi 不提供免费文本搜索；list_markets 的筛选条件就是搜索方式。）
• 研究 — get_market_orderbook、get_market_candlesticks、get_market_trades。
• 深入了解规则 — get_market_rules 汇总市场的 rules_primary/rules_secondary、 提前收盘条件、结算来源和系列禁令；fetch_rules_pdf 会下载实际法律合同 PDF 并提取文本，以供 Agent 阅读。
• 交易所 — get_exchange_status、get_exchange_schedule（市场是否开放以及开放时间）。
• 投资组合 — get_balance、get_positions、get_fills、get_settlements。
• 交易 — create_order、cancel_order、amend_order、decrease_order， 以及 list_orders / get_order。

默认安全

• 除非显式设置 KALSHI_ENV=prod，否则服务默认连接 Kalshi 的 demo（沙盒） 环境。
• 下单工具（create_order、amend_order）要求 confirm=true。未设置时，工具会返回 预览——一份易读摘要和确切的载荷——但不会下单。
• 无需凭据：所有市场和规则工具都可在未认证的情况下使用。只有投资组合和订单工具需要 API 密钥和 RSA 私钥。

直观的订单模型

Kalshi 的 V2 订单 API 从 YES 侧报价所有内容（以定点美元表示的 bid/ask）。 本服务采用更自然的模型——action（买入/卖出）+ side（yes/no）+ 以整 美分为单位的限价——并负责转换（包括买入 NO ⇄ 卖出 YES 时的价格反转）。

配置

变量	默认值	用途
KALSHI_ENV	demo	demo（沙盒）或 prod（真钱）。据此确定基础 URL。
KALSHI_API_KEY	(none)	Kalshi API 密钥 ID。仅认证工具需要。
KALSHI_PRIVATE_KEY_PATH	(none)	RSA 私钥 .pem 的路径。仅认证工具需要。
BASE_URL	(derived)	可选的 REST 基础 URL 覆盖值（必须包含 /trade-api/v2）。

请参阅 .env-example。在 docs.kalshi.com/getting_started/api_keys 获取 API 凭据，并通过 demo environment guide 获取 demo 账户。

Claude Desktop（uvx）

"mcpServers": {
  "kalshi": {
    "command": "uvx",
    "args": ["mcp-server-kalshi"],
    "env": {
      "KALSHI_ENV": "demo",
      "KALSHI_API_KEY": "<YOUR KALSHI API KEY>",
      "KALSHI_PRIVATE_KEY_PATH": "PATH TO YOUR RSA KEY FILE"
    }
  }
}

Claude Desktop（Docker）

"mcpServers": {
  "kalshi": {
    "command": "docker",
    "args": ["run", "--rm", "-i",
      "--mount", "type=bind,src=/Users/username,dst=/Users/username",
      "-e", "KALSHI_ENV", "-e", "KALSHI_API_KEY", "-e", "KALSHI_PRIVATE_KEY_PATH",
      "mcp-server-kalshi"],
    "env": {
      "KALSHI_ENV": "demo",
      "KALSHI_API_KEY": "<YOUR KALSHI API KEY>",
      "KALSHI_PRIVATE_KEY_PATH": "PATH TO YOUR RSA KEY FILE"
    }
  }
}

本地开发

1. 创建 .env 文件（请参阅 .env-example）。
2. 安装依赖：uv sync（开发工具请添加 --extra dev）。需要 Python 3.10+。
3. 运行：uv run start。
4. 测试：uv run pytest。

MCP Inspector

npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-server-kalshi run start

测试与代码质量

uv sync --extra dev              # install dev tools (ruff, mypy, pytest, ...)
uv run pytest                    # run the test suite
uv run pytest --cov              # tests with a coverage report
uv run ruff check src tests      # lint
uv run black src tests           # format (add --check to verify only)
uv run mypy                      # type check
uv run pre-commit install        # (once) run ruff + black on every commit

测试完全离线，不会触及在线 Kalshi API；测试内容包括订单转换和确认门控、HTTP 客户端 （通过注入的 httpx.MockTransport）、MCP 工具注册表、配置以及 PDF 提取。CI（.github/workflows/ci.yml）会在每次推送/PR 时，针对 Python 3.10–3.13 运行 ruff + black + mypy + pytest；发布也必须通过同一套测试。

身份验证

请求使用 RSA-PSS（MGF1-SHA256，最大盐值）签名。每个经过身份验证的请求都会发送 KALSHI-ACCESS-KEY、KALSHI-ACCESS-TIMESTAMP 和 KALSHI-ACCESS-SIGNATURE，其中签名 消息为 timestamp_ms + METHOD + path（路径包含 /trade-api/v2，不包含查询字符串）。