TickDB MCP — Real-time Market Data for AI

📍 本目录是 tickdb-unified-realtime-marketdata-api 仓库的 MCP 服务端实现，提供 13 个 MCP 工具，可作为 Python 包独立部署。

TickDB-MCP 是基于 Model Context Protocol (MCP) 的 Python 服务端实现，通过统一的 REST API 接口为 AI 助手提供实时行情数据（Real-time Market Data）与历史 K 线（Historical K-line）数据。

覆盖 外汇（Forex/FX） · 贵金属（Precious Metals） · 指数（Indices） · 美股（US Stocks / NASDAQ / NYSE） · 港股（HK Stocks） · A 股（A-shares / CN Stocks） · 加密货币（Cryptocurrency），由 13 个 MCP 工具组成，数据来源于 TickDB Unified Market Data API。

链接： 官网 · 文档 · 联系我们

语言： 简体中文 · 繁體中文 · English

快速开始

# 1. 安装 Python 依赖（Python 3.11+）
pip install -e .

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env，填写 TICKDB_API_KEY（前往 https://tickdb.ai 注册获取）

# 3. 启动 MCP 服务端
python main.py          # HTTP 服务，监听 :8000

在 AI 客户端配置中添加（也可直接使用托管端点 https://mcp.tickdb.ai/）：

{
  "mcpServers": {
    "tickdb": {
      "type": "http",
      "url": "https://mcp.tickdb.ai/",
      "headers": {
        "X-TickDB-Key": "YOUR_TICKDB_API_KEY"
      }
    }
  }
}

支持的 AI 客户端：Claude Code · Claude Desktop · Cursor · Kiro · Codex · Zed · Cherry Studio

13 个 MCP 工具

覆盖市场与标的代码格式

配置说明（Configuration）

将 .env.example 复制为 .env：

API Key 优先级： X-TickDB-Key 请求头 → TICKDB_API_KEY 环境变量。

项目结构

tickdb-mcp/
├── main.py                  # 入口文件（Python MCP Server）
├── pyproject.toml           # 包配置与依赖
├── Dockerfile               # Docker 容器化部署
├── .env.example             # 环境变量（Environment）模板
├── tickdb_mcp/              # 核心包
│   ├── config.py            # 配置（Pydantic-settings）
│   ├── client.py            # TickDB REST API HTTP 客户端 + API Key 解析
│   ├── middleware.py        # Bearer Token 鉴权中间件（Middleware）+ Key 注入
│   ├── server.py            # FastMCP 实例工厂
│   └── tools/
│       ├── market.py        # Ticker、K-line、Order Book、Trades、Symbols
│       └── stock.py         # Stock Info、Intraday、Sessions、Metrics、Capital Flow
├── tests/                   # 单元测试（Unit Tests）
│   ├── test_client.py       # API Key 解析与错误处理
│   ├── test_server.py       # MCP 服务创建与工具注册
│   ├── test_middleware.py   # 鉴权与 Accept 头修复
│   └── test_tools.py        # 工具端点映射
├── examples/
│   ├── client_demo.py       # Python MCP 客户端示例
│   └── server_demo.py       # 服务端 smoke test / 工具列表
└── (CI 配置位于上级仓库 ../.github/workflows/mcp-ci.yml)

Docker 部署

# 构建 Docker 镜像
docker build -t tickdb-mcp .

# 运行容器（用户自带 X-TickDB-Key 请求头）
docker run -d -p 8000:8000 tickdb-mcp

# 运行容器（指定服务器统一 API Key）
docker run -d -p 8000:8000 \
  -e TICKDB_API_KEY=YOUR_KEY \
  -e MCP_ACCESS_TOKEN=YOUR_TOKEN \
  tickdb-mcp

开发（Development）

# 安装开发依赖
pip install -e ".[dev]"

# 代码检查（Lint）
ruff check .

# 运行单元测试（Unit Tests）
pytest tests/ -v

# 运行示例
python examples/server_demo.py

文档

贡献指南

1. Fork 本仓库
2. 创建功能分支：git checkout -b feature/my-feature
3. 遵循 PEP 8，由 ruff 强制检查
4. 新功能需包含单元测试（Unit Tests）
5. 提交 PR 并附上清晰的描述

许可证

MIT — 详见 LICENSE。