trading-mcp

Ein MCP-Dienst für Handelsdaten und technische Indikatoren, basierend auf uv + pydantic + akshare + TA-Lib.

Projektinhalt

• Bereitstellung von Abfragen für Aktienmarktdaten und Berechnung grundlegender technischer Indikatoren (K-Linien, RSI, MA, MACD).

• Bereitstellung von Abfragen für mittel- bis langfristige Fundamentaldaten (wichtige A-Aktien-Indikatoren, drei Hauptberichte für US-Aktien, wichtige US-Aktien-Indikatoren).

• Einheitliche Marktdaten-Zugriffsschicht, die A-Aktien und US-Aktien unterstützt (z. B. AAPL.US).

• MCP-Tool-Schnittstelle, die Markdown- oder JSON-Ausgabe unterstützt.

Projektarchitektur

• data/: Marktdaten-Zugriffsschicht. MarketDataClient-Schnittstelle + AkshareMarketDataClient-Implementierung.

• services/: Geschäftsdienstschicht. Konvertiert Rohmarktdaten in eine Standardstruktur und steuert die Indikatorberechnung.

• indicators/: Kapselung der Indikator-Engine. Einheitlicher Aufruf basierend auf TA-Lib.

• models/: Werkzeuganfrage- und Antwortmodelle (Pydantic).

• utils/: MCP-Ausgabeformatierung (Tabellen-Markdown usw.).

• mcp_app.py / main.py: MCP-Diensteinstiegspunkt und Werkzeugregistrierung.

Verzeichnisstruktur

• config/: Konfigurationsdefinitionen (Pydantic Settings).

• data/: Implementierung des Marktdaten-Clients.

• indicators/: Indikator-Berechnungs-Engine.

• models/: Anfrage-/Antwortmodelle.

• services/: Geschäftsdienstschicht.

• tests/: Unit-Tests.

• utils/: Ausgabeformatierung und Hilfswerkzeuge.

• mcp_app.py: MCP-Werkzeugregistrierung.

• main.py: Diensteinstiegspunkt.

Installation und Abhängigkeiten

1. Abhängigkeiten installieren:

uv sync --extra dev

2. TA-Lib-Systembibliotheken installieren:

• macOS: brew install ta-lib

• Debian/Ubuntu: sudo apt-get install libta-lib0 libta-lib0-dev

• Windows: Verwenden Sie das vorkompilierte Wheel für die entsprechende Python-Version

Konfigurationshinweise Die Konfiguration erfolgt über Umgebungsvariablen mit dem Präfix TRADING_MCP_:

export TRADING_MCP_ENVIRONMENT=dev
export TRADING_MCP_DATA_DIR=./data
export TRADING_MCP_DEFAULT_SYMBOL=000001
export TRADING_MCP_HOST=0.0.0.0
export TRADING_MCP_PORT=8000
export TRADING_MCP_AKSHARE_PROXY_ENABLED=true
export TRADING_MCP_AKSHARE_PROXY_AUTH_IP=***
export TRADING_MCP_AKSHARE_PROXY_AUTH_TOKEN=*** TRADING_MCP_AKSHARE_PROXY_RETRY=30

Bedeutung der Felder:

• TRADING_MCP_ENVIRONMENT: Kennung der Laufzeitumgebung (z. B. dev / test / prod).

• TRADING_MCP_DATA_DIR: Lokales Datenverzeichnis.

• TRADING_MCP_DEFAULT_SYMBOL: Standard-Handelsobjekt.

• TRADING_MCP_HOST: Host-Adresse des MCP-Dienstes.

• TRADING_MCP_PORT: Port des MCP-Dienstes.

• TRADING_MCP_AKSHARE_PROXY_ENABLED: Ob akshare-proxy-patch aktiviert werden soll.

• TRADING_MCP_AKSHARE_PROXY_AUTH_IP: Autorisierungs-Gateway-IP für akshare-proxy-patch; wenn nicht konfiguriert, wird der Patch nicht installiert.

• TRADING_MCP_AKSHARE_PROXY_AUTH_TOKEN: Optionales Autorisierungs-Token.

• TRADING_MCP_AKSHARE_PROXY_RETRY: Anzahl der internen Wiederholungsversuche des Patches.

Hinweise zum Anti-Scraping-Proxy von East Money:

• Das Projekt enthält bereits akshare-proxy-patch, der beim Import von data/akshare_client.py automatisch installiert wird.

• Er wird nur aktiviert, wenn TRADING_MCP_AKSHARE_PROXY_AUTH_IP konfiguriert ist und TRADING_MCP_AKSHARE_PROXY_ENABLED=true gesetzt ist.

• Der Patch hookt nur Anfragen an East Money-Domains und beeinträchtigt keine anderen Nicht-Ziel-Websites.

Python-Verwendung

from trading_mcp.config import Settings
from trading_mcp.data import AkshareMarketDataClient
from trading_mcp.indicators import IndicatorEngine

settings = Settings(environment="dev", data_dir="./data", default_symbol="000001")
client = AkshareMarketDataClient()
frame = client.fetch(settings.default_symbol, "2024-01-01", "2024-02-01")

engine = IndicatorEngine()
close_series = frame["close"] if "close" in frame.columns else frame.iloc[:, 0]
result = engine.compute("sma", close_series, timeperiod=5)
print(result.tail())

MCP-Dienst Starten des MCP-Dienstes (streamable HTTP):

python main.py

Starten des MCP Inspector (angepasst für WSL, vom Host-Rechner aus zugänglich):

./dev.sh

Standardmäßig werden folgende Inspector-Konfigurationen verwendet:

• MCP_INSPECTOR_HOST=0.0.0.0

• MCP_INSPECTOR_CLIENT_PORT=6274

• MCP_INSPECTOR_SERVER_PORT=6277

• MCP_INSPECTOR_AUTO_OPEN=false

Im Browser des Windows-Host-Rechners bevorzugt zugreifen über:

http://localhost:6274

Falls die WSL-localhost-Weiterleitung auf dem lokalen Rechner nicht aktiviert ist, können Sie auch hostname -I innerhalb von WSL ausführen, um die IP zu ermitteln, und dann vom Host-Rechner aus auf http://<wsl-ip>:6274 zugreifen.

Wenn Sie nur den Zugriff aus der lokalen Linux-Umgebung wünschen, können Sie dies überschreiben mit:

MCP_INSPECTOR_HOST=127.0.0.1 ./dev.sh

Hinweis: Der Inspector-Proxy hat die Fähigkeit, lokale Prozesse zu starten. 0.0.0.0 sollte nur in vertrauenswürdigen Netzwerkumgebungen verwendet werden.

Verfügbare Werkzeuge:

• trading_kline(symbol, limit=30, offset=0, period_type="1d", start_date=None, end_date=None, response_format="markdown")

• trading_macd(symbol, limit=30, fast_period=12, slow_period=26, signal_period=9, offset=0, period_type="1d", start_date=None, end_date=None, response_format="markdown")

• trading_rsi(symbol, limit=30, period=14, offset=0, period_type="1d", start_date=None, end_date=None, response_format="markdown")

• trading_ma(symbol, limit=30, period=20, ma_type="sma", offset=0, period_type="1d", start_date=None, end_date=None, response_format="markdown")

• trading_volume(symbol, limit=30, offset=0, period_type="1d", start_date=None, end_date=None, response_format="markdown")

• trading_fund_flow_individual_em(symbol, limit=30, offset=0, start_date=None, end_date=None, response_format="markdown")

• trading_fund_flow_individual_rank_em(indicator="5日", limit=30, offset=0, response_format="markdown")

• trading_fund_flow_sector_rank_em(indicator="今日", sector_type="行业资金流", sort_by="主力净流入", limit=30, offset=0, response_format="markdown")

• trading_fund_flow_sector_summary_em(symbol, indicator="今日", limit=30, offset=0, response_format="markdown")

• trading_fundamental_cn_indicators(symbol, indicator="按报告期", limit=30, offset=0, start_date=None, end_date=None, response_format="markdown")

• trading_fundamental_us_report(stock, symbol="资产负债表", indicator="年报", limit=30, offset=0, start_date=None, end_date=None, response_format="markdown")

• trading_fundamental_us_indicators(symbol, indicator="年报", limit=30, offset=0, start_date=None, end_date=None, response_format="markdown")

• trading_industry_summary_ths(limit=30, offset=0, response_format="markdown")

• trading_industry_index_ths(symbol, limit=30, offset=0, start_date=None, end_date=None, response_format="markdown")

• trading_industry_name_em(limit=30, offset=0, response_format="markdown")

• trading_board_change_em(limit=30, offset=0, response_format="markdown")

• trading_industry_spot_em(symbol, limit=30, offset=0, response_format="markdown")

• trading_industry_cons_em(symbol, limit=30, offset=0, response_format="markdown")

• trading_industry_hist_em(symbol, period="日k", adjust="none", limit=30, offset=0, start_date=None, end_date=None, response_format="markdown")

• trading_industry_hist_min_em(symbol, period="5", limit=30, offset=0, response_format="markdown")

• trading_info_global_em(limit=30, offset=0, response_format="markdown")

Parameterhinweise für trading_fundamental_cn_indicators:

• indicator Enum: 按报告期, 按单季度

• symbol kompatible Eingabe: 000001, 000001.SZ, 600519.SH (automatische Vervollständigung oder Normalisierung der Endung)

• Fundamentale Ergebnisse werden im ursprünglichen Zeilenformat zurückgegeben: columns + items

Parameterhinweise für trading_fundamental_us_report:

• symbol (Berichtstyp) Enum: 资产负债表, 综合损益表, 现金流量表

• indicator (Berichtszeitraum) Enum: 年报, 单季报, 累计季报

• stock kompatible Eingabe: TSLA, AAPL.US, 105.AAPL, BRK.B (intern normalisiert auf AkShare-erkennbare Ticker)

Parameterhinweise für trading_fundamental_us_indicators:

• indicator Enum: 年报, 单季报, 累计季报

• symbol kompatible Eingabe: TSLA, AAPL.US, 105.AAPL, BRK.B

• Fundamentale Ergebnisse werden im ursprünglichen Zeilenformat zurückgegeben: columns + items

Feldhinweise für trading_volume:

• Rückgabefelder: timestamp, volume, amount, turnover_rate

• Einheit-Strategie: Beibehaltung der ursprünglichen Einheiten der Datenquelle und Rückgabe der Einheiten über Antwortfelder

  • A-Aktien: volume_unit=lot, amount_unit=CNY

  • US-Aktien: volume_unit=share, amount_unit=USD

  • turnover_rate_unit=percent

• Wenn Wochen-/Monatsdaten aus Tagesdaten aggregiert werden, kann turnover_rate null sein

Hinweise zu Kapitalfluss-Werkzeugen:

• trading_fund_flow_individual_em: Kapitalfluss für Einzelaktien von East Money, symbol unterstützt 000001, 600519.SH, 830799.BJ

• trading_fund_flow_individual_rank_em: Kapitalfluss-Ranking für Einzelaktien von East Money

  • indicator Enum: 今日, 3日, 5日, 10日

• trading_fund_flow_sector_rank_em: Kapitalfluss-Ranking für Sektoren von East Money

  • indicator Enum: 今日, 5日, 10日

  • sector_type Enum: 行业资金流, 概念资金流, 地域资金流

  • sort_by Enum: 涨跌幅, 主力净流入; Standardmäßig absteigend nach 主力净流入

• Wenn die East Money-Ranking-Schnittstelle nicht verfügbar ist:

  • Das Einzelaktien-Ranking greift auf das Kapitalfluss-Ranking von Tonghuashun zurück

  • Das Sektor-/Konzept-Ranking greift auf das entsprechende Ranking von Tonghuashun zurück

  • Nach dem Fallback können die zurückgegebenen Spalten von den ursprünglichen East Money-Spalten abweichen; 地域资金流 hat keinen Fallback

• trading_fund_flow_sector_summary_em: Kapitalfluss für Bestandteile eines bestimmten Sektors

  • Standardmäßig wird East Money verwendet, bei Fehlern Fallback auf Tonghuashun

  • symbol ist der Sektorname, z. B. 电源设备, 风电设备

  • indicator Enum: 今日, 5日, 10日

  • Nach dem Fallback können die zurückgegebenen Spalten von den ursprünglichen East Money-Spalten abweichen

• Kapitalfluss-Ergebnisse werden einheitlich als ursprüngliche Tabelle zurückgegeben: columns + items

Symbolhinweise:

• A-Aktien-Beispiele: 000001, 300308.SZ

• US-Aktien-Beispiele: AAPL.US, AAPL, 105.AAPL, BRK.B

Hinweise zu Branchensektor-Werkzeugen:

• trading_industry_summary_ths: Branchenübersicht von Tonghuashun, gibt ursprüngliche Sektor-Zusammenfassungsfelder zurück

• trading_industry_index_ths: Branchenindex von Tonghuashun, symbol ist der Sektorname, unterstützt start_date / end_date

• trading_industry_name_em: Liste der Branchensektornamen von East Money

• trading_board_change_em: Details zu Sektorveränderungen am Tag von East Money

• trading_industry_spot_em: Echtzeit-Marktdaten für Branchensektoren von East Money, symbol ist der Sektorname

• trading_industry_cons_em: Bestandteile von Branchensektoren von East Money, symbol ist der Sektorname

• trading_industry_hist_em: Historische Marktdaten für Branchensektoren von East Money

  • period Enum: 日k, 周k, 月k

  • adjust Enum: none, qfq, hfq; wobei none keine Anpassung bedeutet

• trading_industry_hist_min_em: Historische Intraday-Marktdaten für Branchensektoren von East Money

  • period Enum: 1, 5, 15, 30, 60

• Branchensektor-Ergebnisse werden einheitlich als ursprüngliche Tabelle zurückgegeben: columns + items

Hinweise zu Nachrichten-Werkzeugen:

• trading_info_global_em: Globale Finanznachrichten von East Money

• Nachrichtenergebnisse werden einheitlich als ursprüngliche Tabelle zurückgegeben: columns + items

Antwortstruktur (structuredContent)

{
  "stock": "TSLA",
  "symbol": "资产负债表",
  "indicator": "年报",
  "columns": ["REPORT_DATE", "ITEM_NAME", "AMOUNT"],
  "items": [],
  "count": 0,
  "total": 0,
  "limit": 30,
  "offset": 0,
  "has_more": false,
  "next_offset": null,
  "start_date": null,
  "end_date": null
}

MCP-Datenaustauschprozess (Architektur- und Sequenzdiagramm)

Im Folgenden wird die aktuelle Hauptarchitektur des Datenaustauschs und das Sequenzdiagramm des MCP mit Mermaid gezeichnet, um den Pfad der Anfragen innerhalb des Systems zu verstehen.

Architekturübersicht (Flowchart)

flowchart LR
  Client[Client / User] -->|HTTP/Stream 请求| MCP[MCP Server]
  MCP -->|调用工具接口| API[Tool Dispatcher / Handlers]
  API --> Market[MarketDataClient (Akshare / Providers)]
  Market -->|行情数据| Storage[Local Cache / Data Dir]
  API --> Indicator[IndicatorEngine (TA-Lib)]
  Indicator -->|指标结果| Formatter[Response Formatter (Markdown / JSON)]
  Formatter -->|返回| Client
  Market -.->|必要时| Proxy[akshare-proxy-patch]
  MCP -->|注册 & 管理| Inspector[MCP Inspector]

Erläuterung:

• MCP Server: Empfängt externe Anfragen (HTTP/Stream), ist für die Analyse der Anfragen und den Aufruf interner Werkzeuge verantwortlich.

• Tool Dispatcher: Leitet Anfragen an das spezifische Werkzeug weiter (z. B. trading_kline, trading_macd).

• MarketDataClient: Einheitliche Marktdaten-Zugriffsschicht, derzeit hauptsächlich mit Akshare implementiert, unterstützt Proxy-Patch.

• IndicatorEngine: Ruft TA-Lib oder interne Algorithmen zur Berechnung technischer Indikatoren auf.

• Response Formatter: Konvertiert strukturierte Daten in das MCP-Antwortformat (Markdown oder JSON).

• Local Cache/Storage: Wird für kurzfristiges Caching und die Speicherung historischer Daten verwendet, um API-Aufrufe zu reduzieren.

Sequenzdiagramm (Sequence Diagram)

sequenceDiagram
  participant U as Client/User
  participant M as MCP Server
  participant D as Tool Dispatcher
  participant MD as MarketDataClient
  participant I as IndicatorEngine
  participant F as Formatter

  U->>M: 发起 trading_macd 请求 (symbol, start, end, params)
  M->>D: 解析并转发请求
  D->>MD: 请求历史 K 线 (symbol, start, end)
  MD-->>D: 返回原始行情数据 (OHLCV)
  D->>I: 传入行情数据与参数, 调用指标计算
  I-->>D: 返回指标结果 (MACD lines, histogram)
  D->>F: 格式化为 Markdown / JSON 的 MCP 响应
  F-->>M: 返回格式化结果
  M-->>U: 通过 HTTP Stream 返回响应 (chunked / 完整)

  alt 缓存命中
    D->>Storage: 读取缓存
    Storage-->>D: 返回缓存数据
  end

  alt 第三方被阻断/需要代理
    MD->>Proxy: 走 akshare-proxy-patch
    Proxy-->>MD: 返回代理后的数据
  end

Die beiden obigen Diagramme sind abstrakte Ansichten des aktuellen Systems; wenn Sie die Diagramme um weitere Komponenten verfeinern möchten (z. B. Authentifizierung, Ratenbegrenzung, Warteschlangen, asynchrone Aufgaben, Überwachungsmetriken), teilen Sie mir mit, welche Teile hinzugefügt werden sollen, und ich kann die Mermaid-Diagramme erweitern und in der README aktualisieren.

Wenn Sie bestätigen, dass diese Aktualisierung in Ordnung ist, werde ich die Änderungen in einen neuen Branch committen, pushen und dann einen Pull Request für Sie zur Überprüfung erstellen.