ak-mcp：AKShare 金融データ MCP Server

ak-mcp は Model Context Protocol（MCP）に基づく金融データ照会サービスで、 AKShare をデータソースとし、公式データ辞書に収録されている 1000+ のデータインターフェースを自動的に MCP ツールとして登録し、Claude、Codex、Cursor などの Agent が直接発見・呼び出しできるようにします。照会結果はデフォルトで MySQL ローカルキャッシュに書き込まれ、 キャッシュヒット時はリモートデータソースにアクセスしないため、ネットワーク依存と遅延を大幅に低減します。

特徴

• 最新の MCP プロトコルに準拠：公式 Python SDK v2（mcp>=2.0）に基づき、2026-07-28 改訂版プロトコルを実装し、2025-11-25 以前のバージョンのクライアントにも自動互換。 同一サービスで stdio と Streamable HTTP の2つのトランスポートを同時にサポート。

• 全インターフェース網羅：インターフェース一覧は公式ドキュメント（https://akshare.akfamily.xyz/data/ ）から直接生成され、現在 1019 個のインターフェースを収録。 株式、先物、債券、オプション、外国為替、通貨、現物、金利、私募/公募ファンド、指数、マクロ、暗号通貨、銀行、エネルギー、オルタナティブデータ、ツールボックス、指標計算など全カテゴリをカバー。

• キャッシュ優先：MySQL キャッシュヒット時はそのまま返却。未ヒット時のみ AKShare にアクセスしてキャッシュに書き戻し。アクセス失敗時は自動的に期限切れデータを返し、stale: true をマーク。

• カテゴリ別 TTL：リアルタイム相場、日次履歴、マクロ指標、静的辞書でそれぞれ異なるキャッシュ有効期限を使用し、関数単位での上書きもサポート。

• ネイティブパラメータ Schema：各ツールのパラメータは AKShare 関数シグネチャから自動生成（必須/任意、型、デフォルト値）。Agent はドキュメントのパラメータに従って直接呼び出せ、追加のラッパー形式を学ぶ必要はありません。

• 運用に優しい：インターフェース検索、キャッシュ統計、キャッシュクリア、ヘルスチェック、キャッシュをバイパスした直接照会などのメタツールを内蔵。

アーキテクチャ

flowchart LR
    A[Agent 客户端<br/>Claude / Codex / Cursor] -->|stdio 或 Streamable HTTP| M[MCP Server<br/>mcp>=2, 2026-07-28]
    M --> T[1000+ 个数据工具<br/>工具名 = AKShare 函数名]
    T --> E[执行器<br/>超时 / 参数过滤 / 结果规范化]
    E --> C{MySQL 缓存<br/>ak_cache}
    C -->|命中且未过期| R[返回 JSON]
    C -->|未命中或过期| K[AKShare]
    K --> C
    K --> D[新浪 / 东财 / 交易所等数据源]
    M --> Meta[元工具<br/>检索 / 统计 / 清理 / 健康]

ディレクトリ構成

ak-mcp/
├── src/ak_mcp/               # 服务端核心代码
│   ├── server.py             # MCP 服务装配与工具注册
│   ├── registry.py           # 文档接口清单加载与安装包匹配
│   ├── schema.py             # 函数签名 -> JSON Schema
│   ├── executor.py           # 线程池调用、超时、参数过滤
│   ├── normalize.py          # DataFrame -> JSON 规范化
│   ├── cache.py              # MySQL 缓存（SQLAlchemy）
│   ├── ttl.py                # TTL 规则引擎
│   ├── config.py             # 环境变量配置
│   └── cli.py                # 命令行入口
├── scripts/
│   ├── build_registry.py     # 抓取官方文档生成接口清单
│   └── init_db.sql           # MySQL 初始化 SQL
├── config/
│   ├── akshare_registry.json # 官方文档接口清单（已生成，1019 个）
│   └── ttl_rules.yaml        # 缓存 TTL 规则
├── tests/                    # 单元与集成测试
├── docker-compose.yml        # MySQL 8 本地环境
├── pyproject.toml
└── Makefile

環境要件

• Python 3.11+（推奨：3.11/3.12/3.13）

• MySQL 8.0+（プロジェクト付属の Docker Compose を使用可能）

• AKShare 公式要件：64 ビット OS

クイックスタート

1. インストール

make install          # 创建 .venv 并安装依赖（等价于 pip install -e ".[dev]"）

2. MySQL の起動

方法1（推奨）：プロジェクト付属の Docker Compose を使用：

make mysql-up         # docker compose up -d mysql，映射标准 3306 端口

方法2：既存の MySQL を使用し、手動で初期化を実行：

mysql -uroot -p < scripts/init_db.sql

3. 設定

cp .env.example .env

必要に応じて .env を変更。デフォルト設定はプロジェクト付属の MySQL コンテナに対応：

MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=ak_mcp
MYSQL_PASSWORD=ak_mcp_password
MYSQL_DB=ak_mcp

全設定項目は .env.example を参照。

4. インターフェース一覧の生成（任意）

リポジトリには config/akshare_registry.json（公式ドキュメント 1.18.94 対応）がコミット済みのため、通常は再生成不要。最新ドキュメントに同期する場合：

make registry

5. サービスの起動

stdio モード（デスクトップクライアントのローカル呼び出し用）：

ak-mcp
# 或 .venv/bin/ak-mcp

Streamable HTTP モード（リモート/マルチクライアント呼び出し用）：

ak-mcp --transport http --host 127.0.0.1 --port 8765

その他のコマンド：

ak-mcp --list-functions          # 打印全部文档接口
ak-mcp --refresh-registry        # 重新抓取官方文档并更新清单
ak-mcp --verbose                 # 调试日志

QuickStart：Agent 接続

Claude Desktop

claude_desktop_config.json（Claude Desktop の MCP 設定）を編集：

{
  "mcpServers": {
    "ak-mcp": {
      "command": "/absolute/path/to/ak-mcp/.venv/bin/ak-mcp",
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "ak_mcp",
        "MYSQL_PASSWORD": "ak_mcp_password",
        "MYSQL_DB": "ak_mcp"
      }
    }
  }
}

保存後、Claude Desktop を再起動すると、stock_zh_a_hist、fund_open_fund_info_em、macro_china_cpi_yearly などの全データツールを会話内で直接使用できます。

Codex

~/.codex/config.toml に追記：

[mcp_servers.ak-mcp]
command = "/absolute/path/to/ak-mcp/.venv/bin/ak-mcp"
env = { MYSQL_HOST = "127.0.0.1", MYSQL_PORT = "3306", MYSQL_USER = "ak_mcp", MYSQL_PASSWORD = "ak_mcp_password", MYSQL_DB = "ak_mcp" }

Codex CLI の MCP 追加コマンドも使用可能（具体的な構文は現在の Codex バージョンの codex mcp --help を参照）。

汎用 MCP クライアント（HTTP）

まず HTTP モードを起動：

ak-mcp --transport http --host 127.0.0.1 --port 8765

その後、URL をサポートする MCP クライアントで設定：

{
  "mcpServers": {
    "ak-mcp": {
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

使用例

A 株の履歴相場を照会

Agent がツール stock_zh_a_hist を直接呼び出し。パラメータは AKShare 公式ドキュメントと同一：

stock_zh_a_hist(symbol="000001", period="daily", start_date="20260801", end_date="20260826", adjust="")

返却 JSON：

{
  "data": [
    {
      "日期": "2026-08-03",
      "开盘": 10.38,
      "收盘": 10.47,
      "最高": 10.59,
      "最低": 10.32,
      "成交量": 886273
    }
  ],
  "meta": {
    "function": "stock_zh_a_hist",
    "params": { "symbol": "000001", "period": "daily" },
    "cached": true,
    "stale": false,
    "rows": 18,
    "elapsed_ms": 2,
    "truncated": false
  }
}

インターフェースの特定

インターフェース名が不明な場合は、まず ak_search_functions を呼び出し：

ak_search_functions(query="可转债 实时行情")
ak_search_functions(category="macro")

運用メタツール

インターフェース一覧の仕組み

1. scripts/build_registry.py が公式ドキュメント data/ ディレクトリ配下の全ページの Markdown ソースファイルを取得し、 接口：xxx、描述：xxx と入力パラメータ表を解析して config/akshare_registry.json を生成。

2. サービス起動時、この一覧を唯一の情報源とする：一覧に収録され、かつインストール済み akshare に存在するインターフェースを、1つずつ MCP ツールとして登録。

3. 一覧にはあるがインストールパッケージに存在しないインターフェースはスキップして警告（例：ドキュメントがバージョンより先に公開された場合）。 AKSHARE_REQUIRE_VERSION_MATCH=true でバージョン一致を強制可能。

キャッシュの仕組み

キャッシュ優先フロー

1. 関数名 + 正規化パラメータ + akshare バージョン から SHA-256 キャッシュキーを計算。

2. ヒットかつ期限切れでない場合：キャッシュ JSON を直接返却（meta.cached = true）。

3. 未ヒットまたは期限切れの場合：AKShare を呼び出してデータを取得し、正規化後に MySQL へ書き戻し。

4. 取得失敗時：期限切れデータが存在する場合は旧データを返し meta.stale = true をマーク。それ以外はエラーテキストを返却。

テーブル構造（ak_cache）

サービス起動時に SQLAlchemy で自動的にテーブルを作成。手動作成の場合は scripts/init_db.sql も参照可能：

TTL ルール

ルールは config/ttl_rules.yaml で定義され、順にマッチングし、先にヒットしたものが有効：

設定項目

開発とテスト

make test          # 运行全部测试（单元 + MCP 内存集成）
make lint          # ruff 检查
make fmt           # ruff 格式化

テスト対象：ドキュメント解析、Schema 生成、TTL 分類、パラメータ正規化、キャッシュキー、SQLite キャッシュ動作、MCP インメモリモードでの ツール登録/呼び出し/エラーハンドリング。実際のネットワークと MySQL を使った統合検証は、ローカルの Docker Compose で手動実行可能 （前述の「エンドツーエンド検証」を参照）。

よくある質問

起動時にインターフェースが見つからないと表示される：Registry function not found in installed akshare: xxx は、公式ドキュメントが現在インストールされている akshare バージョンより先に公開されたことを意味し、このインターフェースはスキップされ、他のインターフェースには影響しません。akshare をアップグレードするか、一覧を再生成してください。

MySQL 接続失敗：.env のポートが docker compose ps の表示と一致しているか確認（本プロジェクトのコンテナは標準ポート 3306 に直接マッピング）。 また、AK_CACHE_ALLOW_DEGRADED=true を設定すると、一時的にキャッシュなしモードで起動できます。

データソースのインターフェースでエラー：AKShare の一部のインターフェースはサードパーティサイト（Sina、East Money など）に依存しており、ネットワーク、リスク管理、フィールド変更の影響を受ける可能性があります。 ak_execute_raw でキャッシュをバイパスして再現するか、akshare バージョンをアップグレードしてください。

タイムゾーンとエンコーディング：キャッシュ時刻は UTC に統一。データの書き込みと読み取りは UTF-8/utf8mb4 を使用し、中国語の列名もそのまま返却可能。

セキュリティと本番環境の推奨事項

• v1 はローカルおよびイントラネット向けで、認証とレート制限は内蔵されていません。本番環境ではゲートウェイの背後（OAuth/API Key、レート制限）に配置することを推奨。

• キャッシュは全 Agent で共有され、ユーザーを区別しません。機密性の高いシナリオでは、ご自身で分離を追加してください。

• HTTP モードを外部に公開する場合は、イントラネットアドレスのみをリッスンするか、リバースプロキシで TLS を追加することを推奨。

License

MIT