✅ Official Alpha Vantage MCP Server

✅ 公式 Alpha Vantage MCP サーバー

株式市場データ API である Alphavantage API 用の MCP サーバーです。

MCP サーバー URL：https://mcp.alphavantage.co

PyPi：https://pypi.org/project/alphavantage-mcp/

設定

API キーの取得

1. 無料の Alphavantage API キーに登録します
2. API キーを ALPHAVANTAGE_API_KEY として環境変数に追加します

インストール

オプション 1：uvx を使用（推奨）

AlphaVantage MCP サーバーを使用する最も簡単な方法は、uvx を使うことです。

# Run directly without installation
uvx alphavantage-mcp

# Or with specific arguments
uvx alphavantage-mcp --server http --port 8080

オプション 2：pip を使用

pip install alphavantage-mcp
alphavantage-mcp

オプション 3：ソースから

git clone https://github.com/calvernaz/alphavantage.git
cd alphavantage
uv run alphavantage

サーバーモード

AlphaVantage サーバーは、2 種類のモードで実行できます。

Stdio サーバー（デフォルト）

これは、Claude Desktop などのツールで使用される標準的な MCP サーバーモードです。

alphavantage
# or explicitly:
alphavantage --server stdio

Streamable HTTP サーバー

このモードでは、HTTP ストリーミングを介してリアルタイムの更新を提供します。

alphavantage --server http --port 8080

OAuth 2.1 認証を使用する Streamable HTTP サーバー

このモードでは、MCP 仕様に従った安全なアクセスのため、HTTP サーバーに OAuth 2.1 認証を追加します。

alphavantage --server http --port 8080 --oauth

OAuth の設定

--oauth フラグを使用する場合、サーバーには環境変数による OAuth 2.1 の設定が必要です。

必須の環境変数：

export OAUTH_AUTHORIZATION_SERVER_URL="https://your-auth-server.com/realms/your-realm"
export OAUTH_RESOURCE_SERVER_URI="https://your-mcp-server.com"

任意の環境変数：

# Token validation method (default: jwt)
export OAUTH_TOKEN_VALIDATION_METHOD="jwt"  # or "introspection"

# For JWT validation
export OAUTH_JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
export OAUTH_JWT_ALGORITHM="RS256"  # default

# For token introspection validation
export OAUTH_INTROSPECTION_ENDPOINT="https://your-auth-server.com/realms/your-realm/protocol/openid-connect/token/introspect"
export OAUTH_INTROSPECTION_CLIENT_ID="your-client-id"
export OAUTH_INTROSPECTION_CLIENT_SECRET="your-client-secret"

# Optional: Required scopes (space-separated)
export OAUTH_REQUIRED_SCOPES="mcp:access mcp:read"

# Optional: Enable session binding for additional security (default: true)
export OAUTH_SESSION_BINDING_ENABLED="true"

OAuth の機能

OAuth の実装では、次の機能を提供します。

• OAuth 2.0 保護リソースメタデータエンドポイント（/.well-known/oauth-protected-resource）
• すべての MCP リクエストに対するベアラートークン認証
• JWT およびトークンイントロスペクションによる検証方式
• MCP セキュリティのベストプラクティスへの準拠：
  • トークンのオーディエンス検証（トークンのパススルー攻撃を防止）
  • 安全なセッション ID によるセッションハイジャックの防止
  • セキュリティ強化のためのユーザーに紐付けられたセッション
  • 401 レスポンスに適切な WWW-Authenticate ヘッダーを設定

例：Keycloak の設定

Keycloak でテストする場合：

# Keycloak OAuth configuration
export OAUTH_AUTHORIZATION_SERVER_URL="https://keycloak.example.com/realms/mcp-realm"
export OAUTH_RESOURCE_SERVER_URI="https://mcp.example.com"
export OAUTH_TOKEN_VALIDATION_METHOD="introspection"
export OAUTH_INTROSPECTION_ENDPOINT="https://keycloak.example.com/realms/mcp-realm/protocol/openid-connect/token/introspect"
export OAUTH_INTROSPECTION_CLIENT_ID="mcp-server"
export OAUTH_INTROSPECTION_CLIENT_SECRET="your-keycloak-client-secret"
export OAUTH_REQUIRED_SCOPES="mcp:access"

# Start server with OAuth
alphavantage --server http --port 8080 --oauth

OAuth クライアントのフロー

OAuth が有効な場合、MCP クライアントは次の手順を実行する必要があります。

1. GET /.well-known/oauth-protected-resource を介して認可サーバーを検出します
2. 認可サーバーに登録します（動的クライアント登録を使用する場合）
3. 認可サーバーからアクセストークンを取得します
4. リクエストにトークンを含めます：Authorization: Bearer <access-token>
5. 401/403 レスポンスに対処し、必要に応じてトークンを更新します

オプション：

• --server：stdio（デフォルト）または http のサーバーモードを選択します
• --port：Streamable HTTP サーバーのポートを指定します（デフォルト：8080）
• --oauth：OAuth 2.1 認証を有効にします（--server http が必要です）

📊 テレメトリ

AlphaVantage MCP サーバーには、監視と可観測性のためのオプションの Prometheus メトリクスが含まれています。

テレメトリの有効化

テレメトリを有効にするには、次の環境変数を設定します。

# Enable telemetry (default: true)
export MCP_TELEMETRY_ENABLED=true

# Server identification (optional)
export MCP_SERVER_NAME=alphavantage
export MCP_SERVER_VERSION=1.0.0

# Metrics server port (default: 9464)
export MCP_METRICS_PORT=9464

メトリクスのエンドポイント

テレメトリが有効な場合、Prometheus メトリクスは次の場所で利用できます。

http://localhost:9464/metrics

利用可能なメトリクス

サーバーは、ツール呼び出しごとに次のメトリクスを収集します。

• mcp_tool_calls_total - ツール呼び出しの総数（ツールと結果別にラベル付け）
• mcp_tool_latency_seconds - ツール実行レイテンシーのヒストグラム
• mcp_tool_request_bytes - リクエストペイロードサイズのヒストグラム
• mcp_tool_response_bytes - レスポンスペイロードサイズのヒストグラム
• mcp_tool_active_concurrency - 実行中の並行ツール呼び出し数のゲージ
• mcp_tool_errors_total - 種類別のエラー総数（タイムアウト、入力不正、接続、その他）

テレメトリを使用した例

# Start server with telemetry enabled
export MCP_TELEMETRY_ENABLED=true
export MCP_SERVER_NAME=alphavantage-prod
export ALPHAVANTAGE_API_KEY=your_api_key
alphavantage --server http --port 8080

# View metrics
curl http://localhost:9464/metrics

🚀 AWS サーバーレスデプロイ

ステートレス MCP パターンを使用して、AlphaVantage MCP Server を AWS Lambda にデプロイし、本番環境に対応したスケーラブルなデプロイを実現します。

AWS へのクイックデプロイ

cd deploy/aws-stateless-mcp-lambda
export ALPHAVANTAGE_API_KEY=your_api_key_here
./deploy.sh

機能：

• ✅ ステートレス MCP パターン - Lambda の実行モデルに最適です
• ✅ 自動スケーリング - AWS Lambda + API Gateway であらゆる負荷に対応します
• ✅ 費用対効果 - リクエスト分のみ課金されます（一般的な使用量で月額約 $1～5）
• ✅ 本番環境対応 - AWS 公式サンプルのパターンに基づいています
• ✅ OAuth 2.1 対応 - 安全なアクセスのためのオプション認証

📖 詳細なドキュメント： セットアップ手順、テスト、モニタリング、トラブルシューティングについては、AWS デプロイガイドをご覧ください。

Claude Desktop での使用

オプション 1：uvx を使用（推奨）

claude_desktop_config.json に以下を追加します。

{
  "mcpServers": {
    "alphavantage": {
      "command": "uvx",
      "args": ["alphavantage-mcp"],
      "env": {
        "ALPHAVANTAGE_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

オプション 2：ソースから実行

リポジトリをクローンした場合は、次の設定を使用します。

{
  "mcpServers": {
    "alphavantage": {
      "command": "uv",
      "args": [
        "--directory",
        "<DIRECTORY-OF-CLONED-PROJECT>/alphavantage",
        "run",
        "alphavantage"
      ],
      "env": {
        "ALPHAVANTAGE_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

ストリーミング可能な HTTP モードでサーバーを実行する

uvx を使用：

{
  "mcpServers": {
    "alphavantage": {
      "command": "uvx",
      "args": ["alphavantage-mcp", "--server", "http", "--port", "8080"],
      "env": {
        "ALPHAVANTAGE_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

ソースから実行：

{
  "mcpServers": {
    "alphavantage": {
      "command": "uv",
      "args": [
        "--directory",
        "<DIRECTORY-OF-CLONED-PROJECT>/alphavantage",
        "run",
        "alphavantage",
        "--server",
        "http",
        "--port",
        "8080"
      ],
      "env": {
        "ALPHAVANTAGE_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

📺 デモ動画

Alpha Vantage MCP Server の動作を簡単にご紹介します。

🔧 開発と公開

PyPI への公開

このプロジェクトには、PyPI と TestPyPI に公開するためのスクリプトが含まれています。

# Publish to TestPyPI (for testing)
python scripts/publish.py --test

# Publish to PyPI (production)
python scripts/publish.py

# Use uv publish instead of twine
python scripts/publish.py --test --use-uv

スクリプトはデフォルトで twine（推奨）を使用しますが、--use-uv フラグを指定して uv publish を使用することもできます。

GitHub Actions

このリポジトリには、自動公開用の GitHub Actions ワークフローが含まれています。

• 信頼された公開：OpenID Connect を使用する PyPA 公式の公開アクションを使用します
• 手動実行：TestPyPI と PyPI のどちらに公開するかを選択して、手動で実行できます
• Twine による代替：信頼された公開と twine ベースの公開の両方に対応しています

公開を設定するには：

1. 信頼された公開の場合（推奨）：

   • PyPI／TestPyPI で、GitHub リポジトリを使用した信頼された公開を設定します
   • OpenID Connect を使用するため、シークレットは不要です

2. トークンベースの公開の場合：

   • リポジトリに PYPI_API_TOKEN と TEST_PYPI_API_TOKEN のシークレットを追加します
   • ワークフローの実行時に「Use twine」オプションを選択します

🤝 貢献

コミュニティからの貢献を歓迎します！始めるには、セットアップ手順、開発のヒント、ガイドラインが記載された貢献ガイドをご覧ください。