StockMCP

📈 StockMCP

Yahoo Finance を使用して、リアルタイムの株式市場データを提供する包括的な Model Context Protocol（MCP）サーバーです

StockMCP は、Model Context Protocol 標準に基づいて構築された、包括的な株式市場データにアクセスするための、JSON-RPC 2.0 準拠の強力なインターフェイスを提供します。AI アプリケーション、金融分析ツール、トレーディングボットに最適です。

🌐 無料のホスト型エンドポイント

セットアップ不要で、すぐに StockMCP をご利用いただけます！ 次の無料ホスト型エンドポイントを提供しています。

• エンドポイント：https://stockmcp.leoguerin.fr/mcp
• API キー不要 — MCP クライアントの設定に追加するだけです

Claude Desktop の設定

すぐにアクセスするには、claude_desktop_config.json に次の設定を使用してください。

{
  "mcpServers": {
    "stock-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://stockmcp.leoguerin.fr/mcp",
        "--header",
        "--allow-http"
      ]
    }
  }
}

設定ファイルの場所：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\\Claude\\claude_desktop_config.json

🛠️ 利用可能なツール

ツール名	説明
get_realtime_quote	価格、出来高、時価総額、主要な財務比率など、現在の市場データを取得します
get_fundamentals	包括的な財務諸表（損益計算書、貸借対照表、キャッシュフロー）と算出済みの比率を取得します
get_price_history	再投資した配当を含むオプションのトータルリターン計算とともに、過去の OHLCV データを取得します
get_dividends_and_actions	品質指標と一貫性スコアを用いて、配当支払い履歴と企業行動を分析します
get_analyst_forecasts	専門アナリストによる目標株価、コンセンサス評価（買い／保有／売り）、EPS 予測を取得します
get_growth_projections	売上高、利益（EPS）、フリーキャッシュフローの将来成長予測と、1 年、3 年、5 年の CAGR 推定値を取得します

🚀 クイックスタート

API キーの設定

1. 無料の Alpha Vantage API キーを取得する：https://www.alphavantage.co/support/#api-key にアクセスします
2. 環境を設定する：

   # Copy the example environment file
   cp .env.example .env
   
   # Edit .env and add your API key
   ALPHAVANTAGE_KEY=your-actual-api-key-here
   

Docker を使用する（推奨）

# Clone the repository
git clone https://github.com/yourusername/StockMCP.git
cd StockMCP

# Configure your API key (see API Key Setup above)
cp .env.example .env
# Edit .env with your Alpha Vantage API key

# Build and run with Docker
docker build -t stockmcp .
docker run -p 3001:3001 --env-file .env stockmcp

ローカル開発

# Install dependencies with uv (fastest)
uv sync

# Or with pip
pip install -e .

# Configure your API key (see API Key Setup above)
cp .env.example .env
# Edit .env with your Alpha Vantage API key

# Run the server
python src/main.py
# Server runs on http://localhost:3001/mcp

MCP クライアントとの統合

サーバーの起動後、MCP クライアントと統合します。

Claude Desktop

設定ファイルを編集します。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

次の設定を追加します。

{
  "mcpServers": {
    "stock-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3001/mcp",
        "--header",
        "--allow-http"
      ]
    }
  }
}

Cursor

MCP の設定に追加します。

{
  "stock-mcp": {
    "command": "npx",
    "args": [
      "mcp-remote",
      "http://localhost:3001/mcp",
      "--header",
      "--allow-http"
    ]
  }
}

その他の MCP クライアント

MCP 対応のクライアントでは、次の情報を使用してください。

• エンドポイント：http://localhost:3001/mcp
• プロトコル：HTTP 経由の JSON-RPC 2.0
• ツール：tools/list メソッドから利用できます

詳細な API の例と JSON スキーマについては、サーバーの実行中に http://localhost:3001/mcp/docs でインタラクティブなドキュメントを参照してください。

🔗 使用方法

StockMCP は、AI アプリケーションとのシームレスな統合のために Model Context Protocol（MCP）を実装しています。起動すると、サーバーは次の機能を提供します。

• エンドポイント：http://localhost:3001/mcp
• プロトコル：HTTP 経由の JSON-RPC 2.0
• 検出：tools/list を使用して利用可能なツールを取得します
• 実行：tools/call を使用して、パラメーターを指定してツールを実行します

🛠️ 開発

プロジェクト構成

StockMCP/
├── src/
│   ├── main.py              # FastAPI server and endpoints
│   ├── models.py            # Pydantic models for MCP and stock data
│   ├── mcp_handlers.py      # MCP protocol request handlers
│   ├── tools.py             # Tools package entry point
│   └── tools/               # Modular tools implementation
│       ├── market_data.py   # Real-time quotes, history, fundamentals
│       ├── analysis.py      # Forecasts and growth projections
│       └── registry.py      # Tool registration and execution
├── tests/                   # Comprehensive test suite (100 tests)
├── Dockerfile              # Container configuration
├── pyproject.toml          # Project dependencies and configuration
└── README.md              # This file

テストの実行

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run specific test file
uv run pytest tests/test_api.py

# Run with coverage
uv run pytest --cov=src

依存関係

コア依存関係：

• FastAPI - API 向けのモダンな Web フレームワーク
• Pydantic - Python の型ヒントを使用したデータ検証
• yfinance - Yahoo Finance データの取得（主なデータソース）
• pandas - データの操作と分析
• scipy - 科学技術計算（yfinance に必要）

開発依存関係：

• pytest - テストフレームワーク
• httpx - テスト用 HTTP クライアント
• pytest-mock - モック用ユーティリティ

🐳 Docker デプロイ

ビルドと実行

# Build the image
docker build -t stockmcp .

# Run the container
docker run -p 3001:3001 stockmcp

# Run in background
docker run -d -p 3001:3001 --name stockmcp-server stockmcp

環境設定

コンテナーはデフォルトでポート 3001 で API を公開します。次のようにカスタマイズできます。

# Custom port mapping
docker run -p 8080:3001 stockmcp

# With environment variables
docker run -p 3001:3001 -e LOG_LEVEL=DEBUG stockmcp

🔧 設定

サーバー設定

サーバーは環境変数で設定できます。

• LOG_LEVEL - ログレベル（DEBUG、INFO、WARNING、ERROR）
• HOST - サーバーのホスト（デフォルト：0.0.0.0）
• PORT - サーバーのポート（デフォルト：3001）

API の制限とデータソース

主なデータソース：Yahoo Finance（yfinance）

• 無料プランで、適切なレート制限が設定されています
• リアルタイムデータと履歴データを利用できます
• 基本的な使用には API キーは不要です

副次的なデータソース：Alpha Vantage（任意）

• 充実した業績予想と予測を利用できます
• 拡張機能の利用には無料の API キーが必要です
• 利用できない場合は、適切にフォールバックします

本番環境での推奨事項：

• リクエストのキャッシュを実装する
• 指数バックオフによるリトライ処理を追加する
• API の使用パターンを監視する
• データソースの冗長化を検討する

🤝 コントリビューション

コントリビューションを歓迎します。始める手順は次のとおりです。

1. リポジトリをフォークする
2. 機能ブランチを作成する（git checkout -b feature/amazing-feature）
3. 適切なテストを用意して変更を加える
4. テストスイートを実行する（uv run pytest）
5. 変更をコミットする（git commit -m 'Add amazing feature'）
6. ブランチにプッシュする（git push origin feature/amazing-feature）
7. プルリクエストを作成する

開発ガイドライン

• 型ヒント - すべての関数に適切な型注釈を付けてください
• テスト - 新機能には包括的なテストを含めてください
• ドキュメント - API を変更した場合は、README と docstring を更新してください
• コードスタイル - PEP 8 に従い、意味の分かりやすい変数名を使用してください

📝 ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細は LICENSE ファイルを参照してください。

🙏 謝辞

• Yahoo Finance - 無料の株式市場データを提供してくださったことに感謝します
• Model Context Protocol - 優れたプロトコル仕様に感謝します
• FastAPI - 素晴らしい Web フレームワークに感謝します
• Pydantic - 堅牢なデータ検証に感謝します

📞 サポート

• 🐛 バグ報告 - Issue を作成
• 💡 機能リクエスト - ディスカッションを開始
• 📖 ドキュメント - 詳細な API ドキュメントをご確認ください
• 💬 コミュニティ - 質問やアイデアについては、ディスカッションにご参加ください

---