ak-mcp: AKShare Finanzdaten-MCP-Server

ak-mcp ist ein Finanzdaten-Abfragedienst auf Basis des Model Context Protocol (MCP), der AKShare als Datenquelle nutzt und die über 1000 Datenschnittstellen aus dem offiziellen Datenwörterbuch automatisch als MCP-Tools registriert, damit Agenten wie Claude, Codex und Cursor sie direkt finden und aufrufen können. Abfrageergebnisse werden standardmäßig in den lokalen MySQL-Cache geschrieben; bei Cache-Treffern wird die entfernte Datenquelle nicht mehr aufgerufen, wodurch Netzwerkabhängigkeit und Latenz deutlich reduziert werden.

Funktionen

• Befolgt das neueste MCP-Protokoll: Basierend auf dem offiziellen Python-SDK v2 (mcp>=2.0), implementiert es das am 28.07.2026 überarbeitete Protokoll und ist automatisch kompatibel mit Clients vom 25.11.2025 und früher; derselbe Dienst unterstützt gleichzeitig stdio und Streamable HTTP als Transport.

• Vollständige Schnittstellenabdeckung: Die Schnittstellenliste wird direkt aus der offiziellen Dokumentation (https://akshare.akfamily.xyz/data/) generiert und umfasst derzeit 1019 Schnittstellen, die alle Hauptkategorien abdecken: Aktien, Futures, Anleihen, Optionen, Devisen, Geldmarkt, Spot, Zinssätze, Privat-/Publikumsfonds, Indizes, Makro, Kryptowährungen, Banken, Energie, alternative Daten, Werkzeuge, Indikatorberechnung usw.

• Cache zuerst: MySQL-Cache-Treffer werden direkt zurückgegeben; nur bei Fehltreffern wird AKShare als Quelle aufgerufen und der Cache zurückgeschrieben; bei Quellfehlern werden automatisch abgelaufene Daten zurückgegeben und mit stale: true markiert.

• TTL nach Kategorie: Echtzeitkurse, tägliche historische Daten, Makroindikatoren und statische Wörterbücher verwenden jeweils unterschiedliche Cache-Gültigkeitsdauern, mit Unterstützung für Überschreibung pro Funktion.

• Natives Parameter-Schema: Die Parameter jedes Tools werden automatisch aus der AKShare-Funktionssignatur generiert (erforderlich/optional, Typ, Standardwert). Agenten können direkt mit den Dokumentationsparametern aufrufen, ohne ein zusätzliches Verpackungsformat zu erlernen.

• Betriebsfreundlich: Integrierte Metatools für Schnittstellensuche, Cache-Statistiken, Cache-Bereinigung, Health-Check und Direktabfrage unter Umgehung des Caches.

Architektur

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/>检索 / 统计 / 清理 / 健康]

Verzeichnisstruktur

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

Systemanforderungen

• Python 3.11+ (empfohlen: 3.11/3.12/3.13)

• MySQL 8.0+ (das mitgelieferte Docker Compose des Projekts kann verwendet werden)

• AKShare erfordert offiziell ein 64-Bit-Betriebssystem

Schnellstart

1. Installation

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

2. MySQL starten

Option 1 (empfohlen): Das mitgelieferte Docker Compose des Projekts verwenden:

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

Option 2: Eine vorhandene MySQL-Instanz verwenden und die Initialisierung manuell ausführen:

mysql -uroot -p < scripts/init_db.sql

3. Konfiguration

cp .env.example .env

.env nach Bedarf anpassen. Die Standardkonfiguration entspricht dem mitgelieferten MySQL-Container des Projekts:

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

Alle Konfigurationsoptionen finden Sie in .env.example.

4. Schnittstellenliste generieren (optional)

Das Repository enthält bereits config/akshare_registry.json (entspricht der offiziellen Dokumentation 1.18.94); eine Neugenerierung ist normalerweise nicht erforderlich. Zum Synchronisieren mit der neuesten Dokumentation:

make registry

5. Dienst starten

stdio-Modus (für lokale Aufrufe durch Desktop-Clients):

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

Streamable-HTTP-Modus (für entfernte/mehrere Clients):

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

Weitere Befehle:

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

QuickStart: Agent-Integration

Claude Desktop

claude_desktop_config.json bearbeiten (die MCP-Konfiguration von Claude Desktop):

{
  "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"
      }
    }
  }
}

Nach dem Speichern Claude Desktop neu starten. Alle Datentools wie stock_zh_a_hist, fund_open_fund_info_em und macro_china_cpi_yearly sind dann direkt im Dialog verfügbar.

Codex

In ~/.codex/config.toml anhängen:

[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" }

Alternativ kann der MCP-Hinzufügen-Befehl der Codex-CLI verwendet werden (die genaue Syntax richtet sich nach der aktuellen Codex-Version: codex mcp --help).

Allgemeine MCP-Clients (HTTP)

Zuerst den HTTP-Modus starten:

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

Dann in einem MCP-Client, der URLs unterstützt, konfigurieren:

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

Verwendungsbeispiele

A-Aktien-Historie abfragen

Der Agent ruft direkt das Tool stock_zh_a_hist auf, mit Parametern gemäß der offiziellen AKShare-Dokumentation:

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

JSON-Antwort:

{
  "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
  }
}

Schnittstelle finden

Wenn der Schnittstellenname unklar ist, zuerst ak_search_functions aufrufen:

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

Betriebs-Metatools

Mechanismus der Schnittstellenliste

1. scripts/build_registry.py ruft die Markdown-Quelldateien aller Seiten im data/-Verzeichnis der offiziellen Dokumentation ab, parst 接口：xxx, 描述：xxx und die Eingabeparametertabelle und generiert config/akshare_registry.json.

2. Beim Dienststart dient diese Liste als einzige Quelle: Alle in der Liste enthaltenen und in der installierten akshare-Version vorhandenen Schnittstellen werden einzeln als MCP-Tools registriert.

3. Schnittstellen, die in der Liste, aber nicht im Installationspaket vorhanden sind, werden übersprungen und mit einer Warnung versehen (z. B. wenn die Dokumentation vor der Version veröffentlicht wurde); mit AKSHARE_REQUIRE_VERSION_MATCH=true kann eine Versionsübereinstimmung erzwungen werden.

Cache-Mechanismus

Cache-zuerst-Ablauf

1. SHA-256-Cache-Schlüssel aus Funktionsname + normalisierte Parameter + akshare-Version berechnen.

2. Treffer und nicht abgelaufen: Cache-JSON direkt zurückgeben (meta.cached = true).

3. Fehltreffer oder abgelaufen: AKShare als Quelle aufrufen, normalisieren und in MySQL zurückschreiben.

4. Quellfehler: Wenn abgelaufene Daten vorhanden sind, alte Daten zurückgeben und mit meta.stale = true markieren; andernfalls Fehlertext zurückgeben.

Tabellenstruktur (ak_cache)

Die Tabelle wird beim Dienststart automatisch über SQLAlchemy erstellt; alternativ kann sie manuell gemäß scripts/init_db.sql erstellt werden:

TTL-Regeln

Die Regeln sind in config/ttl_rules.yaml definiert, werden der Reihe nach abgeglichen, der erste Treffer gewinnt:

Konfigurationsoptionen

Entwicklung und Tests

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

Die Tests decken ab: Dokumentationsparsing, Schema-Generierung, TTL-Klassifizierung, Parameternormalisierung, Cache-Schlüssel, SQLite-Cache-Verhalten, Tool-Registrierung/-Aufruf/-Fehlerbehandlung im MCP-In-Memory-Modus. Die Integrationsverifikation mit echtem Netzwerk und MySQL kann manuell über das lokale Docker Compose ausgeführt werden (siehe „End-to-End-Verifikation“ oben).

Häufig gestellte Fragen

Beim Start wird gemeldet, dass eine Schnittstelle nicht gefunden wurde: Registry function not found in installed akshare: xxx bedeutet, dass die offizielle Dokumentation vor der aktuell installierten akshare-Version veröffentlicht wurde. Diese Schnittstelle wird übersprungen, ohne andere zu beeinträchtigen; akshare aktualisieren oder die Liste neu generieren.

MySQL-Verbindungsfehler: Prüfen, ob der Port in .env mit der Ausgabe von docker compose ps übereinstimmt (der Container dieses Projekts bildet direkt den Standardport 3306 ab); alternativ kann AK_CACHE_ALLOW_DEGRADED=true gesetzt werden, um vorübergehend im Modus ohne Cache zu starten.

Fehler der Datenquellen-Schnittstelle: Einige AKShare-Schnittstellen hängen von Drittanbieter-Websites ab (Sina, East Money usw.) und können durch Netzwerk, Risikokontrolle oder Feldänderungen beeinträchtigt werden; über ak_execute_raw kann der Cache umgangen werden, um den Fehler zu reproduzieren, oder die akshare-Version aktualisiert werden.

Zeitzone und Kodierung: Die Cache-Zeiten sind einheitlich in UTC; Daten werden mit UTF-8/utf8mb4 geschrieben und gelesen, chinesische Spaltennamen können direkt zurückgegeben werden.

Sicherheits- und Produktionsempfehlungen

• v1 ist für lokale und interne Netzwerke gedacht und enthält keine integrierte Authentifizierung oder Ratenbegrenzung; in der Produktion wird empfohlen, den Dienst hinter einem Gateway zu platzieren (OAuth/API-Key, Ratenbegrenzung).

• Der Cache wird von allen Agenten gemeinsam genutzt, ohne Benutzerunterscheidung; bei sensiblen Szenarien bitte selbst für Isolierung sorgen.

• Bei externer Bereitstellung des HTTP-Modus wird empfohlen, nur auf der internen Netzwerkadresse zu lauschen oder TLS über einen Reverse-Proxy hinzuzufügen.

Lizenz

MIT