trading-mcp

uv + pydantic + akshare + TA-Lib をベースに構築された、取引データおよびテクニカル指標のMCPサービスです。

プロジェクトの内容

• 株式相場データの照会と基本的なテクニカル指標（ローソク足、RSI、MA、MACD）の計算機能を提供。

• 中長期的なファンダメンタルズデータの照会（A株の主要指標、米国株の三大財務諸表、米国株の主要指標）を提供。

• A株および米国株（例：AAPL.US）をサポートする統一された市場データアクセス層。

• MarkdownまたはJSON出力をサポートするMCPツールインターフェース。

プロジェクトアーキテクチャ

• data/：市場データアクセス層。MarketDataClient インターフェース + AkshareMarketDataClient 実装。

• services/：ビジネスサービス層。生の相場データを標準構造に変換し、指標計算を駆動。

• indicators/：指標エンジンのカプセル化。TA-Libに基づいた統一呼び出し。

• models/：ツールリクエストおよびレスポンスモデル（Pydantic）。

• utils/：MCP出力のフォーマット（テーブルMarkdownなど）。

• mcp_app.py / main.py：MCPサービスのエントリポイントとツール登録。

ディレクトリ構造

• config/：設定定義（Pydantic Settings）。

• data/：市場データクライアントの実装。

• indicators/：指標計算エンジン。

• models/：リクエスト/レスポンスモデル。

• services/：ビジネスサービス層。

• tests/：ユニットテスト。

• utils/：出力フォーマットおよび補助ツール。

• mcp_app.py：MCPツール登録。

• main.py：サービス起動エントリポイント。

インストールと依存関係

1. 依存関係のインストール：

uv sync --extra dev

2. TA-Libシステムライブラリのインストール：

• macOS: brew install ta-lib

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

• Windows: 対応するPythonバージョンのプリコンパイル済みwheelを使用

設定説明 設定は環境変数 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

フィールドの意味：

• TRADING_MCP_ENVIRONMENT：実行環境識別子（例：dev / test / prod）。

• TRADING_MCP_DATA_DIR：ローカルデータディレクトリ。

• TRADING_MCP_DEFAULT_SYMBOL：デフォルトの相場対象。

• TRADING_MCP_HOST：MCPサービスのリスニングアドレス。

• TRADING_MCP_PORT：MCPサービスのポート。

• TRADING_MCP_AKSHARE_PROXY_ENABLED：akshare-proxy-patch を有効にするかどうか。

• TRADING_MCP_AKSHARE_PROXY_AUTH_IP：akshare-proxy-patch 認証ゲートウェイIP。未設定時はパッチをインストールしません。

• TRADING_MCP_AKSHARE_PROXY_AUTH_TOKEN：オプションの認証トークン。

• TRADING_MCP_AKSHARE_PROXY_RETRY：パッチ内部の再試行回数。

東方財富（East Money）アンチスクレイピングプロキシの説明：

• プロジェクトには akshare-proxy-patch が組み込まれており、data/akshare_client.py をインポートする際に自動的にインストールを試みます。

• TRADING_MCP_AKSHARE_PROXY_AUTH_IP が設定され、かつ TRADING_MCP_AKSHARE_PROXY_ENABLED=true の場合のみ有効になります。

• パッチは東方財富関連のドメインリクエストのみをフックし、他のターゲット外サイトには影響しません。

Pythonでの使用方法

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サービス MCPサービス（streamable HTTP）の起動：

python main.py

MCP Inspectorの起動（WSL対応、ホストマシンからアクセス可能）：

./dev.sh

デフォルトでは以下のInspector設定が使用されます：

• MCP_INSPECTOR_HOST=0.0.0.0

• MCP_INSPECTOR_CLIENT_PORT=6274

• MCP_INSPECTOR_SERVER_PORT=6277

• MCP_INSPECTOR_AUTO_OPEN=false

Windowsホストマシンのブラウザからは以下に優先的にアクセスしてください：

http://localhost:6274

ローカルマシンでWSLの localhost 転送が有効になっていない場合は、WSL内で hostname -I を実行してIPを確認し、ホストマシンから http://<wsl-ip>:6274 にアクセスしてください。

ローカルのLinux環境のみでアクセスしたい場合は、以下のように上書き可能です：

MCP_INSPECTOR_HOST=127.0.0.1 ./dev.sh

注意：Inspectorプロキシはローカルプロセスを起動する機能を持っています。0.0.0.0 は信頼できるネットワーク環境でのみ使用してください。

利用可能なツール：

• 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")

trading_fundamental_cn_indicators パラメータ説明：

• indicator 列挙：按报告期、按单季度

• symbol 互換入力：000001、000001.SZ、600519.SH（自動補完または正規化されたサフィックス）

• ファンダメンタルズ結果は元の行形式で返されます：columns + items

trading_fundamental_us_report パラメータ説明：

• symbol（レポートタイプ）列挙：资产负债表、综合损益表、现金流量表

• indicator（レポート期間）列挙：年报、单季报、累计季报

• stock 互換入力：TSLA、AAPL.US、105.AAPL、BRK.B（内部でAkShareが認識できるtickerに正規化）

trading_fundamental_us_indicators パラメータ説明：

• indicator 列挙：年报、单季报、累计季报

• symbol 互換入力：TSLA、AAPL.US、105.AAPL、BRK.B

• ファンダメンタルズ結果は元の行形式で返されます：columns + items

trading_volume フィールド説明：

• 返されるフィールド：timestamp、volume、amount、turnover_rate

• 単位戦略：データソースの元の単位を保持し、レスポンスフィールドを通じて単位を返します

  • A株：volume_unit=lot、amount_unit=CNY

  • 米国株：volume_unit=share、amount_unit=USD

  • turnover_rate_unit=percent

• 週次/月次が日次データから集計される場合、turnover_rate は null になる可能性があります

資金フローツールの説明：

• trading_fund_flow_individual_em：東方財富の個別銘柄資金フロー、symbol は 000001、600519.SH、830799.BJ をサポート

• trading_fund_flow_individual_rank_em：東方財富の個別銘柄資金フローランキング

  • indicator 列挙：今日、3日、5日、10日

• trading_fund_flow_sector_rank_em：東方財富のセクター資金フローランキング

  • indicator 列挙：今日、5日、10日

  • sector_type 列挙：行业资金流、概念资金流、地域资金流

  • sort_by 列挙：涨跌幅、主力净流入；デフォルトは 主力净流入 の降順

• 東方財富のランキングインターフェースが利用できない場合：

  • 個別銘柄ランキングは同花順（10jqka）の個別銘柄資金フローランキングにフォールバックします

  • 業界/概念セクターランキングは同花順の対応するランキングにフォールバックします

  • フォールバック後の返される列は、東方財富の元の列と異なる場合があります；地域资金流 はフォールバックしません

• trading_fund_flow_sector_summary_em：指定セクターの構成銘柄資金フロー

  • デフォルトで東方財富を使用し、失敗した場合は同花順にフォールバックします

  • symbol はセクター名（例：电源设备、风电设备）

  • indicator 列挙：今日、5日、10日

  • フォールバック後の返される列は、東方財富の元の列と異なる場合があります

• 資金フローの結果は、元のテーブル形式で統一して返されます：columns + items

シンボルの説明：

• A株の例：000001、300308.SZ

• 米国株の例：AAPL.US、AAPL、105.AAPL、BRK.B

業界セクターツールの説明：

• trading_industry_summary_ths：同花順の業界一覧表、元のセクター集計フィールドを返します

• trading_industry_index_ths：同花順の業界指数、symbol はセクター名、start_date / end_date をサポート

• trading_industry_name_em：東方財富の業界セクター名リスト

• trading_board_change_em：東方財富の当日のセクター変動詳細

• trading_industry_spot_em：東方財富の業界セクターリアルタイム相場、symbol はセクター名

• trading_industry_cons_em：東方財富の業界セクター構成銘柄、symbol はセクター名

• trading_industry_hist_em：東方財富の業界セクター履歴相場

  • period 列挙：日k、周k、月k

  • adjust 列挙：none、qfq、hfq；none は権利落ち調整なしを意味します

• trading_industry_hist_min_em：東方財富の業界セクター分足履歴相場

  • period 列挙：1、5、15、30、60

• 業界セクターの結果は、元のテーブル形式で統一して返されます：columns + items

ニュースツールの説明：

• trading_info_global_em：東方財富のグローバル金融ニュース速報

• ニュースの結果は、元のテーブル形式で統一して返されます：columns + items

レスポンス構造（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データインタラクションフロー（アーキテクチャとシーケンス図）

以下は、現在のMCPの主要なデータインタラクションアーキテクチャとシーケンス図をMermaidで描画したものです。システム内でのリクエストの流転経路を理解するのに役立ちます。

アーキテクチャ図（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]

説明：

• MCP Server：外部リクエスト（HTTP/stream）を受信し、リクエストの解析と内部ツールの呼び出しを担当します。

• Tool Dispatcher：リクエストを特定のツール（例：trading_kline、trading_macd）にルーティングします。

• MarketDataClient：統一された市場データアクセス層。現在は主にAkshareで実装されており、プロキシパッチをサポートしています。

• IndicatorEngine：TA-Libまたは組み込みアルゴリズムを呼び出してテクニカル指標を計算します。

• Response Formatter：構造化データをMarkdownまたはJSONのMCPレスポンス形式に変換します。

• Local Cache/Storage：API呼び出しを減らすための短期キャッシュおよび履歴データストレージ。

シーケンス図（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

上記の2つの図は現在のシステムの抽象的なビューです。もし図をより多くのコンポーネント（例：認証、レート制限、キュー、非同期タスク、監視指標）に詳細化したい場合は、必要な部分を教えてください。Mermaid図を拡張してREADMEを更新します。

この更新に問題がないことを確認いただければ、変更を新しいブランチにコミットしてプッシュし、レビュー用のプルリクエストを作成します。