TickDB MCP

---

TickDB とは？

TickDB は、開発者、AI エージェント、マルチマーケット金融アプリケーション向けの AI ネイティブなリアルタイム市場データ API（AI-native real-time market data API）です。

**一度の接続（one connection）**で、外国為替（Forex）、貴金属（Precious Metals）、指数（Indices）、米国株（US Stocks / NASDAQ / NYSE）、香港株（HK Stocks）、A 株（A-Shares）、中国および香港の先物（China/Hong Kong Futures）、暗号資産（Cryptocurrency）など、複数の金融市場のリアルタイムおよび過去の市場データにシームレスにアクセスできます。

TickDB は、信頼性が高く、低遅延で、長期的に利用できる市場データを必要とする開発者向けに構築されています。複数のデータソース、プロトコル、プロバイダーを管理する複雑さを回避し、ビジネスや戦略そのものに専念できます。

ティック単位の約定（tick-by-tick trades）、板情報（order book / depth）、ローソク足（candlestick）など、さまざまな形式の市場データに対応しています。 REST API と WebSocket で接続でき、クオンツ取引、AI エージェント、リアルタイム市場データシステム、取引プラットフォーム、データ分析の用途をカバーします。

---

すぐに利用を開始

このリポジトリでは完全なソースコードを提供しています：SKILL/（AI スキル、インターフェースリファレンスを含む）· mcp/（Python MCP サーバー、43 個のツール · Dockerfile · 自動テスト · CI · MIT）。mcp/ を使ってセルフホストすることも、公開ホストエンドポイント mcp.tickdb.ai を利用することもできます。

ご自身に合った接続方法を選んでください：

方法	対象	説明
Skill	AI チャットですぐに利用、設定不要	npx でワンクリックインストールし、AI が試用キーを自動取得します
MCP	AI コーディングクライアント／オープンソースのセルフホスト	mcp/ を使ってセルフホストするか、ホスト型 OAuth／リクエストヘッダーで接続します
CLI	ターミナル／スクリプト／AI エージェント	npm でグローバルインストールし、コマンドラインから市場データを直接照会します
REST API	アプリケーション連携	市場データ、先物、財務ファンダメンタルズ向けの HTTP API
WebSocket	リアルタイムのストリーミングデータ	低遅延で ticker / depth / trade を購読

---

主な特長

• 統一された接続：単一の API で外国為替、貴金属、指数、米国株、香港株、A 株、中国および香港の先物、暗号資産に対応
• リアルタイムデータ：WebSocket によるストリーミング配信で、エンドツーエンドの遅延は約 10〜50ms
• 企業財務・ファンダメンタルズ：REST API で米国株、香港株、A 株の財務諸表、PE 評価、収益構成、株主、企業イベントを照会
• AI ネイティブ：公式の Skill／MCP／CLI という 3 つの AI 接続方法を提供し、AI エージェントやコーディングアシスタントですぐに利用可能
• 開発者に使いやすい：RESTful API + WebSocket、構造化された JSON レスポンス、充実したドキュメントと多言語のサンプル
• グローバルな市場カバレッジ：株式、外国為替、貴金属、指数、中国および香港の先物、暗号資産を網羅。銘柄と数量は製品カタログの返却内容に準じます
• 無料で開始：クレジットカード不要で、すぐに API キーを取得できます

---

主な利用シーン

• クオンツ取引（Quantitative Trading）：アルゴリズムや戦略システム向けのリアルタイム市場データソース
• AI エージェント／コーディングアシスタント：Skill／MCP を通じて AI アシスタントが市場データを直接呼び出し、自然言語で照会を実行
• 市場データダッシュボード：リアルタイム価格の表示、資産やポートフォリオの監視
• 取引アプリケーション：TradingView のような市場データ画面やチャートシステムの構築
• データ分析とバックテスト（Backtesting）：過去の市場データ分析、戦略のバックテストや調査
• 金融サービスとの連携：既存の取引プラットフォームや金融インフラへの統合
• セルフホスト／プライベート環境への導入：ホスト型エンドポイントを使いたくない場合は、このリポジトリの mcp/ コードを使ってセルフホストし、データフローを完全に管理できます

---

クイックスタート — REST API

単一の REST API で、市場データと企業財務・ファンダメンタルズを照会できます。財務 API には、財務諸表、評価、株主保有状況、分類別の経済カレンダーが含まれます。

認証と基本情報 · 市場データの主要 API · 企業財務・ファンダメンタルズ API

認証と基本情報

TickDB.ai にアクセスしてアカウントを登録すると、API キーを取得できます。

認証

すべての HTTP API リクエストで、リクエストヘッダーに API キーを含める必要があります：

X-API-Key: YOUR_API_KEY

ベース URL

https://api.tickdb.ai

API キーのサブスクリプション照会

• GET /v1/apikeys/subscriptions — 現在認証されているアカウントの API キーについて、プラン、状態、有効期限を照会します

対応市場

市場タイプ	Symbol 形式の例	説明
外国為替（Forex / FX）	GBPUSD	主要通貨ペア（Base/Quote）
貴金属（Precious Metals）	XAUUSD	米ドル建ての貴金属ペア（Commodity / USD）
米国株（US Stocks）	AAPL.US	NYSE / NASDAQ 上場株式
指数（Indices）	SPX	株価指数（例：S&P 500）
香港株（HK Stocks）	700.HK	香港証券取引所上場証券
A 株（A-Shares）	600519.SH	上海／深圳証券取引所の株式
中国先物（China Futures）	AP8888	type=futures、market=CN。具体的な契約および連続契約はカタログを参照してください
香港先物（HK Futures）	HSI8888	type=futures、market=HK。具体的な契約および連続契約はカタログを参照してください
暗号資産（Cryptocurrency）	BTCUSDT	暗号資産の取引ペア

先物では、リアルタイム市場データ、ローソク足、板情報、ティック単位の約定照会に対応しています。ローソク足では建玉 open_interest を返すことができます。銘柄コードは /v1/symbols/available?type=futures から照会する必要があります。通常の契約は限月とともに変わります。7777、8888、9999 は、それぞれ次限月、主力、加重連続を表します。連続契約は実際に受渡し可能な契約を意味しません。上の表はコード形式のみを示しており、データの利用可否は銘柄とキーの権限によって異なります。

市場データの主要 API

通用行情

• GET /v1/symbols/available — 产品目录，含中国及香港期货
• GET /v1/market/ticker — 指定品种的实时行情快照
• GET /v1/market/kline — 历史 K 线
• GET /v1/market/kline/latest — 当前周期的实时 K 线
• GET /v1/market/depth — 买卖盘口深度
• GET /v1/market/trades — 逐笔成交（Tick-by-Tick Trades）

全量行情快照

• GET /v1/market/ticker/cn-stock — A 股全量行情快照
• GET /v1/market/ticker/hk-stock — 港股全量行情快照
• GET /v1/market/ticker/us-stock — 美股全量行情快照

股票行情与市场资讯

• GET /v1/market/stock-info — 股票基本信息
• GET /v1/market/intraday — 股票当日分时
• GET /v1/market/kline/ex-factors — 股票复权因子
• GET /v1/market/calc-index — 股票综合指标
• GET /v1/market/capital-flow — 股票资金流向
• GET /v1/market/trading-sessions — 市场交易时段
• GET /v1/market/trade-days — 市场交易日历

获取 K 线（K-line）数据

curl -H "X-API-Key: YOUR_API_KEY" \
     "https://api.tickdb.ai/v1/market/kline?symbol=700.HK&interval=1h&limit=24"

获取实时行情（Ticker）数据

curl -H "X-API-Key: YOUR_API_KEY" \
     "https://api.tickdb.ai/v1/market/ticker?symbols=AAPL.US,700.HK,BTCUSDT"

获取盘口深度（Depth）数据

curl -H "X-API-Key: YOUR_API_KEY" \
     "https://api.tickdb.ai/v1/market/depth?symbol=AAPL.US"

获取逐笔成交（Tick-by-Tick Trades）数据

curl -H "X-API-Key: YOUR_API_KEY" \
     "https://api.tickdb.ai/v1/market/trades?symbol=AAPL.US&limit=20"

查询可用交易品种

curl -H "X-API-Key: YOUR_API_KEY" \
     "https://api.tickdb.ai/v1/symbols/available?market=HK&limit=10"

查询中国及香港期货目录：

curl -H "X-API-Key: YOUR_API_KEY" "https://api.tickdb.ai/v1/symbols/available?type=futures&market=CN&limit=10"
curl -H "X-API-Key: YOUR_API_KEY" "https://api.tickdb.ai/v1/symbols/available?type=futures&market=HK&limit=10"

公司财务与基本面 API

财务与基本面提供 29 个 HTTP 端点，覆盖美股、港股和 A 股；直接使用同一 Base URL 与 X-API-Key，无需经过 MCP。数据覆盖取决于品种、披露时间和 Key 的接口及市场权限。

公司概况

• GET /v1/fundamentals/profile — 公司资料
• GET /v1/fundamentals/executives — 高管与董事
• GET /v1/fundamentals/segments/latest — 最新业务与地区营收构成
• GET /v1/fundamentals/segments/history — 历史营收构成

财务报表

• GET /v1/fundamentals/financials/latest — 最新财报：利润表、资产负债表、现金流量表
• GET /v1/fundamentals/financials/annual — 年度财务报表
• GET /v1/fundamentals/financials/ttm — TTM 利润表与现金流量表

估值与行业

• GET /v1/fundamentals/valuation/latest — 最新 PE 估值
• GET /v1/fundamentals/valuation/ts — 历史 PE 时序
• GET /v1/fundamentals/industry/peers — 同业公司对比
• GET /v1/fundamentals/industry/dist — 个股行业指标分布
• GET /v1/fundamentals/industries/rank — 市场行业排行
• GET /v1/fundamentals/industries/tree — 行业分类层级

分红与公司行动

• GET /v1/fundamentals/dividends — 历史与已知未来分红事件
• GET /v1/fundamentals/dividends/ttm — 过去 12 个月每股现金股息
• GET /v1/fundamentals/buyback — 公司回购
• GET /v1/fundamentals/corp-actions — 公司资本行动

股东与基金持仓

• GET /v1/fundamentals/shareholders/latest — 最新股东持仓
• GET /v1/fundamentals/shareholders/top — 多个报告期的主要股东
• GET /v1/fundamentals/shareholders/detail — 股东持仓与交易详情
• GET /v1/fundamentals/fund-holdings/latest — 持有该股票的基金

财经日历

• GET /v1/fundamentals/calendar/report — 财报与业绩日历
• GET /v1/fundamentals/calendar/dividend — 分红日历
• GET /v1/fundamentals/calendar/split — 拆股与合股日历
• GET /v1/fundamentals/calendar/ipo — 发行与上市日历
• GET /v1/fundamentals/calendar/other — 其他分类事件

新闻与市场状态

• GET /v1/fundamentals/news — 公司新闻列表
• GET /v1/fundamentals/news/{news_id} — 新闻正文或节选
• GET /v1/fundamentals/market/status — 美股、港股、A 股市场状态

详细参数、响应字段与错误码见官方 API 文档。

查询财务报表

以下示例分别查询最近四期利润表、最近三年资产负债表与 TTM 现金流量表：

curl -H "X-API-Key: YOUR_API_KEY" "https://api.tickdb.ai/v1/fundamentals/financials/latest?symbol=AAPL.US&type=stock&kind=IS&n=4"
curl -H "X-API-Key: YOUR_API_KEY" "https://api.tickdb.ai/v1/fundamentals/financials/annual?symbol=AAPL.US&type=stock&kind=BS&n=3"
curl -H "X-API-Key: YOUR_API_KEY" "https://api.tickdb.ai/v1/fundamentals/financials/ttm?symbol=AAPL.US&type=stock&kind=CF"

查询 PE 估值与分红

curl -H "X-API-Key: YOUR_API_KEY" "https://api.tickdb.ai/v1/fundamentals/valuation/latest?symbol=AAPL.US&type=stock"
curl -H "X-API-Key: YOUR_API_KEY" "https://api.tickdb.ai/v1/fundamentals/dividends?symbol=AAPL.US&type=stock&limit=20"

查询分类财报日历

curl -H "X-API-Key: YOUR_API_KEY" "https://api.tickdb.ai/v1/fundamentals/calendar/report?market=US&symbols=AAPL.US&limit=100"

---

实时订阅 — WebSocket

低延迟（10-50ms）的流式数据推送，适合实时行情看板、量化策略与 Agent 自动化场景。

普通行情订阅

• ticker — 指定品种的实时行情
• depth — 买卖盘口更新
• trade — 逐笔成交实时推送

全量行情订阅

• CN_Stock — A 股全量行情
• HK_Stock — 港股全量行情
• US_Stock — 美股全量行情

连接控制与使用说明

• ping / pong — 连接心跳检测
• unsubscribe — 取消订阅

全量行情需在连接时协商 permessage-deflate；消息格式、心跳、断线重连与恢复订阅见官方连接指南。

マルチマーケットの購読と圧縮（Node.js）

以下の例では、Node.js の ws ライブラリを使用します。まず npm install ws を実行し、環境変数 TICKDB_API_KEY を設定します。コードを market-stream.cjs として保存し、node market-stream.cjs を実行してください。購読する銘柄と全市場の集合は Key の権限に準拠する必要があります。コードは製品カタログから実際に返された内容に基づいています。通常の相場情報のみが必要な場合は、fullMarkets を空の配列に設定してください。

perMessageDeflate は new WebSocket で直接有効にします。圧縮はハンドシェイク時にネゴシエーションされ、ws がメッセージを自動的に解凍します。この例では、通常の単一メッセージと、全量スナップショットおよび差分更新の配列メッセージの両方を処理します。ブラウザーのネイティブ WebSocket では、このオプションを受け付けません。

const WebSocket = require('ws');

const apiKey = process.env.TICKDB_API_KEY;
if (!apiKey) throw new Error('Set TICKDB_API_KEY before running this example');

const tickerSymbols = [
    'EURUSD', // 外汇
    'XAUUSD', // 贵金属
    'SPX', // 指数
    'AAPL.US', // 美股
    '700.HK', // 港股
    '600519.SH', // A 股
    'AP8888', // 中国期货
    'HSI8888', // 香港期货
    'BTCUSDT', // 加密货币
];
const depthSymbols = ['AAPL.US', '700.HK', '600519.SH', 'AP8888', 'BTCUSDT'];
const tradeSymbols = [...depthSymbols, 'HSI8888'];
const fullMarkets = ['CN_Stock', 'HK_Stock', 'US_Stock'];

const endpoint = new URL('wss://api.tickdb.ai/v1/realtime');
endpoint.searchParams.set('api_key', apiKey);
const ws = new WebSocket(endpoint, {
    perMessageDeflate: true // 在连接握手时协商 permessage-deflate 压缩，ws 自动解压。
});

ws.on('open', () => {
    if (fullMarkets.length && !ws.extensions.includes('permessage-deflate')) {
        console.error('Full-market data requires permessage-deflate');
        ws.close();
        return;
    }

    // 混合产品类型时省略 type；有歧义的代码按类型另行订阅。
    ws.send(JSON.stringify({
        cmd: 'subscribe',
        data: { channel: 'ticker', symbols: tickerSymbols }
    }));
    // 盘口示例：美股、港股、A 股、中国期货与加密货币。
    ws.send(JSON.stringify({
        cmd: 'subscribe',
        data: { channel: 'depth', symbols: depthSymbols }
    }));
    // 逐笔成交示例额外包含香港期货。
    ws.send(JSON.stringify({
        cmd: 'subscribe',
        data: { channel: 'trade', symbols: tradeSymbols }
    }));

    // 全量与个股 ticker 独立订阅，可同时使用，不影响 depth 和 trade。
    if (fullMarkets.length) {
        ws.send(JSON.stringify({
            cmd: 'subscribe',
            data: { universes: fullMarkets, channels: ['ticker'] }
        }));
    }
});

ws.on('message', (raw) => {
    let payload;
    try {
        payload = JSON.parse(raw.toString());
    } catch {
        console.error('Received an invalid JSON message');
        return;
    }

    // 普通推送为对象；全量快照和增量更新为数组。
    for (const message of Array.isArray(payload) ? payload : [payload]) {
        if (['ticker', 'depth', 'trade'].includes(message.cmd)) {
            console.log(message.cmd, message.data);
        } else if (message.cmd === 'error') {
            console.error('Subscription error:', message.code, message.message);
        }
    }
});

ws.on('error', () => {
    console.error('WebSocket connection failed');
});

---

AI 接続

TickDB は AI-native な相場データ API です。3 段階のネイティブ接続方式を提供し、設定不要の対話から本番環境向けの高度な統合まで、あらゆるニーズに対応します。

Skill — 対話ですぐに利用

インストール後、AI が試用 Key を自動で取得するため、登録なしで一覧にある 62 銘柄を照会できます。

npx clawhub@latest install tickdb-market-data

または、このリポジトリに含まれる SKILL/ ディレクトリ全体をクライアントの Skill ディレクトリにコピーし、tickdb-market-data という名前を付けてください。SKILL.md と references/ はそのまま残します。相場情報、調整済み K 線、先物、財務ファンダメンタルズ、API Key のプランと有効期限の照会に対応しています。実際に利用できる範囲は Key の権限によって異なります。

MCP — 永続的な統合

このリポジトリの MCP と Skill は 43 個の REST エンドポイントに対応しており、前述の 3 市場の全量相場情報と WebSocket 機能は含まれません。

一度設定すれば、AI アシスタントは MCP サービスを通じて 43 個のツール：相場情報ツール 13 個、企業財務・ファンダメンタルズツール 29 個、API Key の購読照会ツール 1 個を利用できます。

機能	ユーザーが照会できる内容
相場情報と株式（13 ツール）	リアルタイム価格、調整済み K 線、調整係数、売買板、約定ごとの取引、資金フロー、先物銘柄
企業財務・ファンダメンタルズ（29 ツール）	企業情報、財務諸表、PE 評価、業種、株主の保有状況、配当・自社株買い、ニュース、分類別の経済カレンダー
API Key の購読（1 ツール）	現在の Key が属するアカウントについて返されるプラン、ステータス、有効期限、残り時間

相場情報は外国為替、貴金属、指数、米国株、香港株、A 株、中港先物、暗号資産を対象としています。企業財務・ファンダメンタルズは米国株、香港株、A 株を対象としており、利用可否は銘柄、開示時期、プランの権限によって異なります。

セルフデプロイ： mcp/ の Python ソースコードまたは Dockerfile を使用してください。下記のデプロイガイドを参照してください。Web OAuth はデフォルトで無効になっています。ガイドに従って設定すると有効にできます。

ローカル起動（Python 3.11+）： Linux ターミナルでリポジトリのルートディレクトリから実行してください。初回インストール時は .env をコピーし、アップグレード時は既存の設定を保持してください。

cd mcp
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
cp .env.example .env
# 编辑 .env，填写 TICKDB_API_KEY；也可由客户端通过请求头提供 Key
python main.py

ローカルサービスのアドレスは http://localhost:8000/mcp です。Docker と HTTPS OAuth の設定については、セルフデプロイガイドを参照してください。

公開ホスト型エンドポイント（任意、セルフデプロイ不要）：

• Web OAuth 接続（ChatGPT / Claude）： サーバー URL に https://mcp.tickdb.ai/oauth を使用し、OAuth を選択します。TickDB の認証ページでご自身の API Key を確認し、認可を確定してください。
• リクエストヘッダー接続（AI コーディングクライアント）： https://mcp.tickdb.ai/ を使用し、X-TickDB-Key で API Key を渡します。設定は以下のとおりです。

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

各クライアントの設定および Claude Desktop のローカル stdio モードについては、下記の接続ガイドを参照してください。

**MCP サーバーはオープンソースです。**コードはこのリポジトリの mcp/ ディレクトリにあります。

mcp/ の概要：v0.2.3 · MCP ツール 43 個 · Python 3.11+ · Docker 対応 · 自動テスト · MIT ライセンス · CI による継続的な検証

ドキュメント	リンク
クライアント接続設定	mcp/MCP_CLIENT_SETUP.md
デプロイ手順（セルフデプロイ）	mcp/DEPLOYMENT.md
MCP 完全ドキュメント	mcp/README.md
Web OAuth 接続とセルフデプロイの設定	MCP OAuth 設定
バージョン更新履歴	MCP Changelog

CLI — ターミナル＆エージェント

npm install -g tickdb
tickdb config set-key YOUR_API_KEY
tickdb ticker BTCUSDT,XAUUSD

詳しくは公式サイトの AI 接続ページを参照してください。

---

オンラインドキュメント

API リファレンス、パラメーターの説明、すぐに実行できるリクエスト例の全文：

• Docs: https://docs.tickdb.ai
• 公式サイト: https://tickdb.ai
• AI 接続ページ: https://tickdb.ai/ai-tools

---

コミュニティとサポート

• GitHub Issues：バグの報告または機能のリクエスト
• テクニカルサポート：Telegram
• メール：[email protected]
• ドキュメント：docs.tickdb.ai

---

ライセンス

このドキュメントは MIT ライセンスに基づいています。