Stock MCP

🚀 株式MCPサーバー

Model Context Protocolに基づくスマート株式データサービスで、中国株（A股）、香港株（港股）、米国株（美股）のリアルタイムデータをワンストップで取得し、AIによる深層分析も提供します。

クイックスタート • 主な機能 • APIドキュメント • 設定ガイド

✨ なぜStock MCPを選ぶのか？

• 🌐 世界市場カバー - 中国株（A股）、香港株（港股）、米国株（美股）のデータにワンクリックでアクセスできます。
• 🤖 AIスマート分析 - ニュースの感情分析、深層調査レポート、スマート検索機能を備えています。
• 🚀 すぐに使える - Dockerでワンクリックでデプロイし、5分でサービスを起動できます。
• 📊 複数のデータソースの融合 - AKShare、Tushare、yFinance、Finnhubなどのデータをスマートに集約します。
• 💾 高性能キャッシュ - Redisによる高速化と自動ダウングレード機能で、安定した動作を保証します。

🚀 クイックスタート

# 1. プロジェクトをクローンする
git clone <your-repo-url> && cd stock-mcp

# 2. 環境変数を設定する（必須：TUSHARE_TOKEN）
cp .env.example .env && vim .env

# 3. ワンクリックで起動する
docker-compose up -d

# 4. サービスにアクセスする
open http://localhost:9998/docs

🎯 5分で核心機能を体験する：

# 茅台の過去の価格とAI分析を取得する
curl "http://localhost:9998/stock/price?symbol=600519&start_date=2024-01-01&end_date=2025-01-01"

# アップルのリアルタイム相場を取得する
curl "http://localhost:9998/api/stock/news?symbol=AAPL"

# 株式の基本データを取得する
curl "http://localhost:9998/api/stock/fundamental?symbol=000008&curr_date=2025-06-01"

# 複数の株式を一括で取得する
curl -X POST "http://localhost:9998/api/stock/quotes" \
  -H "Content-Type: application/json" \
  -d '{"symbols": ["AAPL", "TSLA", "MSFT"]}'

✨ 主な機能

📋 APIインターフェースの概要

💡 ヒント: すべてのインターフェースは中国株（A股）、香港株（港股）、米国株（美股）の3大市場をサポートしています。
📚 詳細ドキュメント: 起動後、http://localhost:9998/docs にアクセスしてください。

📊 データ照会機能

• ✅ リアルタイム相場 - 分単位の価格/出来高
• ✅ 過去のデータ - K線図、除權価格
• ✅ 財務報告 - 貸借対照表、キャッシュフロー
• ✅ テクニカル指標 - MACD、RSI、ボリンジャーバンド
• ✅ 資金の流れ - 主力資金、北向資金

🤖 AI強化

• 🔍 スマート検索 - Tavilyの意味検索
• 📰 感情分析 - 複数のニュースソースの集約 + 評価
• 📈 深層調査 - AIによる調査レポートの生成
• 💡 意思決定支援 - データ駆動型の投資アドバイス
• 🌐 多言語対応 - 中国語と英語の自動識別

⚙️ 設定説明

核心設定（.envファイル）

# 【必須】中国株（A股）データへのアクセス（申請先：https://tushare.pro/）
TUSHARE_TOKEN=your_token_here

# 【オプション】プロキシ設定（米国株データへのアクセス時に推奨）
HTTP_PROXY=http://127.0.0.1:7890
HTTPS_PROXY=http://127.0.0.1:7890

# 【オプション】拡張機能
TAVILY_API_KEY=your_key     # AI検索と調査
FINNHUB_API_KEY=your_key    # 拡張ニュースデータ
NEWS_API_KEY=your_key       # ニュース集約

📡 APIインターフェースドキュメント

🎨 インタラクティブドキュメント

サービスを起動した後、以下のURLにアクセスして、完全なSwagger UIドキュメントを表示します：

• Swagger UI: http://localhost:9998/docs
• ReDoc: http://localhost:9998/redoc

📊 株式データインターフェース

{
  "status": "success",
  "message": "株式価格データと分析レポートの取得に成功しました。",
  "data": "# AAPL株式分析レポート\n\n## 📊 基本情報\n- **株式名**: アップル社\n- **株式コード**: AAPL\n- **分析期間**: 2025-07-12 から 2025-08-12\n\n## 💰 価格の推移\n- **現在の価格**: $227.18\n- **期間内の値動き**: $+18.80 (+9.02%)\n- **期間内の最高値**: $230.74\n- **期間内の最低値**: $201.27\n- **平均出来高**: 60,489,490\n\n## 📈 テクニカル指標\n- **5日移動平均線**: $218.35\n- **20日移動平均線**: $212.25\n- **最近のトレンド**: 上昇"
}

curl -X GET "http://localhost:9998/stock/price?symbol=AAPL&start_date=2024-07-13&end_date=2025-07-13" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

curl -X GET "http://localhost:9998/api/stock/fundamental?symbol=000008&curr_date=2025-06-01" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

{
  "status": "success",
  "message": "AAPLのリアルタイム相場の取得に成功しました。",
  "data": {
    "ticker": "AAPL",
    "currentPrice": "256.48",
    "dailyChangePercent": "-0.0818107444777616",
    "peRatio": "38.919575",
    "marketCap": "3806263246848",
    "source": "yfinance"
  }
}

curl -X GET "http://localhost:9998/api/stock/news?symbol=AAPL" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

curl -X POST "http://localhost:9998/api/stock/quotes" \
  -H "Content-Type: application/json" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903" \
  -d '{"symbols": ["AAPL", "TSLA", "MSFT"]}'

📰 ニュースデータインターフェース

curl -X GET "http://localhost:9998/api/stock/news?symbol=000001" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

curl -X GET "http://localhost:9998/api/stock/news/date?symbol=000001&target_date=2025-09-10&days_before=7" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

📅 取引日カレンダーインターフェース

curl -X GET "http://localhost:9998/api/calendar/trading-days?symbol=000001&start_date=2025-01-01&end_date=2025-09-01" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

curl -X GET "http://localhost:9998/api/calendar/is-trading-day?symbol=000001&check_date=2025-09-30" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

curl -X GET "http://localhost:9998/api/calendar/trading-hours?symbol=000001&check_date=2025-09-30" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

{
  "status": "success",
  "message": "サポートされている取引所のリストの取得に成功しました。",
  "data": {
    "total_count": 200,
    "regions": {
      "アメリカ": ["NYSE", "NASDAQ"],
      "中国": ["XSHG", "XSHE"],
      "ヨーロッパ": ["XPAR", "XLON"],
      "アジア太平洋": ["NSE", "TSE"],
      "カナダ": ["TSX"]
    },
    "all_exchanges": ["NYSE", "NASDAQ", "XSHG", "XSHE", "..."]
  }
}

curl -X GET "http://localhost:9998/api/calendar/supported-exchanges" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

🔐 認証説明

すべてのAPIインターフェースは、オプションの Authorization ヘッダーを使用した認証をサポートしています。

-H "Authorization: your-api-token-here"

トークンの取得: 管理者に連絡するか、設定ファイルでカスタムトークンを設定してください。

📊 クイックテスト

以下のコマンドを使用して、主要なインターフェースをすばやくテストできます。

# 茅台の株価を照会する
curl "http://localhost:9998/stock/price?symbol=600519&start_date=2024-01-01&end_date=2025-01-01"

# アップルのリアルタイム相場を取得する
curl "http://localhost:9998/api/stock/news?symbol=AAPL"

# 今日が取引日かどうかをチェックする
curl "http://localhost:9998/api/calendar/is-trading-day?symbol=000001&check_date=$(date +%Y-%m-%d)"

# すべてのサポートされている取引所を取得する
curl "http://localhost:9998/api/calendar/supported-exchanges"

📖 API設計規範

このプロジェクトのAPIは、以下の設計原則に従っています。

✅ RESTfulスタイル - 標準のHTTPメソッド(GET/POST)を使用します。
✅ 統一されたレスポンス形式 - すべてのインターフェースは統一されたJSON構造を返します。
✅ 詳細なエラー情報 - エラーレスポンスには明確なエラーコードと説明が含まれています。
✅ OpenAPI 3.0 - 完全なAPI仕様ドキュメント（参照）
✅ 自動ドキュメント生成 - Swagger UIとReDocの両方のドキュメントをサポートしています。

🐳 Dockerデプロイ

サービスアーキテクチャ

一般的なコマンド

# サービスを起動する
docker-compose up -d

# ログを表示する
docker-compose logs -f stock-mcp

# サービスを停止する
docker-compose down

# サービスを再起動する
docker-compose restart

# 再構築する
docker-compose up -d --build

🛠️ トラブルシューティング

# 設定を確認する
cat .env | grep REDIS_HOST
# Docker環境では: REDIS_HOST=redis を使用することを確認する

# Redisの状態を確認する
docker-compose ps redis

# プロキシ設定を確認する
cat .env | grep PROXY
# Docker環境では: HTTP_PROXY=http://host.docker.internal:7890 を使用する

grep TUSHARE_TOKEN .env

その他の問題：完全なトラブルシューティングガイドを参照してください。

📚 ドキュメント

• 📡 完全なAPIドキュメント - すべてのインターフェースの詳細な説明、パラメータ、例
• 💡 API使用例 - 実際のシナリオでのコード例
• 📖 使用ガイド - 設定、デプロイ、ベストプラクティス
• 🔧 開発ドキュメント - アーキテクチャ設計、二次開発
• 🌐 OpenAPI仕様 - 標準のAPI仕様ファイル
• 💻 Swagger UI - インタラクティブなAPIテスト（サービス起動後にアクセス）

🤝 貢献の参加

IssueとPull Requestの提出を歓迎します！

# 1. プロジェクトをForkする
# 2. 機能ブランチを作成する
git checkout -b feature/amazing-feature

# 3. コードをコミットする
git commit -m "Add: amazing feature"

# 4. プッシュしてPRを作成する
git push origin feature/amazing-feature

📄 ライセンス

MITライセンス - 詳細は LICENSE を参照してください。

🙏 謝辞

このプロジェクトは、以下の優れたオープンソースプロジェクトに基づいて構築されています。

MCP • FastAPI • AKShare • Tushare • yFinance • Tavily

⭐️ もしこのプロジェクトが役に立ったら、Starをしてください⭐️