finnhub-mcp-server

---

概要

Finnhub から米国株のリアルタイムデータを取得できます。株価、企業のファンダメンタルズ、決算、アナリストの推奨、金融ニュースに対応しています。finnhub_search_symbols で企業名をシンボルに解決した後、任意の MCP クライアントから、その企業のリアルタイム価格、評価、ニュースを取得できます。stdio プロセスまたはローカルの Streamable HTTP サーバーとして動作します。

ツール

ツール	説明
finnhub_search_symbols	企業名またはティッカーの一部から株式シンボルを検索し、米国銘柄の可能性が最も高いものを先頭に表示します。他のすべてのツールで最初に使用します。
finnhub_get_quote	米国の 1 銘柄のリアルタイム株価を、市場のリアルタイム状況と組み合わせて返します。価格がリアルタイムのものか前日の終値かを、返された取引セッションと祝日の名称も含めて示します。
finnhub_get_company	1 回の呼び出しで企業の全体像を取得します。プロフィール、主要なファンダメンタルズ（P/E、EPS、利益率、成長率）、同じセクターの企業が含まれます。
finnhub_get_earnings	決算情報を 2 つのモードで取得します。銘柄の過去の四半期決算と実績対予想のサプライズ（history）、または指定した日付範囲内の今後の発表（任意で銘柄による絞り込みが可能）（calendar）です。
finnhub_get_news	金融ニュースを 2 つのモードで取得します。日付範囲内の特定銘柄に関する最近の記事（company）、またはカテゴリ別の市場全般のヘッドライン（market）です。
finnhub_get_recommendations	米国の 1 銘柄について、アナリストの推奨動向を取得します。月ごとの強い買い／買い／保有／売り／強い売りの件数を、新しい順に返します。

リソース

リソース	説明
finnhub://news-categories	有効な市場ニュースカテゴリ（general、forex、crypto、merger）と、それぞれの1行の説明です。

finnhub_get_news の category 列挙型ですべてカバーされているため、ツールのみを使用するクライアントでも機能が失われることはありません。

機能リファレンス

finnhub_search_symbols _ツール

• query（1～20文字）と limit（1～50、デフォルトは10）を指定して、企業名またはティッカーの一部から検索します。
• 米国の普通株式と思われる銘柄を優先して返します。isLikelyUS の銘柄形式に基づくヒューリスティック、合計一致件数、切り捨てに関する説明も返します。株価と企業プロフィールのレスポンスが確定情報です。

---

finnhub_get_quote _ツール

• symbol が必要です。現在の価格、変動額、取引セッションの始値／高値／安値、前日終値、ISO 8601形式の株価時刻を返します。
• priceIsLive は現在の価格がリアルタイム価格か前日終値かを示します。市場状況を取得できない場合、marketOpen、session、holiday は null になります。不明なティッカーの場合は symbol_not_found、米国以外の銘柄または有料プラン限定の銘柄の場合は not_us_or_paid が返されます。

---

finnhub_get_company _ツール

• symbol が必要です。企業プロフィール、取得できない場合は null となる主要ファンダメンタル指標（P/E、EPS、52週レンジ、ベータ、配当利回り、利益率、成長率、ROE）、セクターの同業他社を返します。
• 取得に失敗した指標や同業他社は partial に表示されます。symbol_not_found と not_us_or_paid のエラーはプロフィールに基づいて判定されます。

---

finnhub_get_earnings _ツール

• history は symbol が必要で、過去の四半期の実績／予想EPSとサプライズを新しい順に返します。calendar は from／to（デフォルトは今日から14日後まで）を受け取り、任意で symbol も指定できます。決算発表日、EPS／売上高の予想、発表時刻を返します。
• limit（1～100、デフォルトは50）で行数を制限し、合計件数と切り捨てに関する説明を返します。symbol を指定せずに履歴を取得すると missing_symbol、米国以外の銘柄または有料プラン限定の銘柄の場合は not_us_or_paid が返されます。

---

finnhub_get_news _ツール

• company では symbol が必要で、日付範囲を指定できます（デフォルトは直近7日間）。market では category に general、forex、crypto、merger のいずれかを指定します（finnhub://news-categories を参照）。
• 見出し、情報源、ISO 8601形式の日時、要約、URLを新しい順に返します。limit（1～100、デフォルトは15）で記事数を制限し、合計件数と切り捨てに関する説明を返します。symbol を指定せずに企業ニュースを取得すると missing_symbol、米国以外の銘柄または有料プラン限定の銘柄の場合は not_us_or_paid が返されます。

---

finnhub_get_recommendations _ツール

• 月ごとの強い買い／買い／ホールド／売り／強い売りの件数を、新しい順に返します（通常、過去12～24か月分）。
• limit（1～24、デフォルトは12、つまり1年分）で件数を制限します。対象月の合計件数を報告し、切り捨てについて説明します。
• 結果が空の場合（アナリストによるカバーがない場合）は no_coverage が返されます。これは無効な銘柄とは異なります。米国以外の銘柄または有料プラン限定の銘柄の場合は not_us_or_paid が返されます。

---

finnhub://news-categories _リソース

• 有効な finnhub_get_news の市場モードカテゴリ（general、forex、crypto、merger）と、それぞれの1行の説明を application/json として返します。
• 利便性のためのミラーです。finnhub_get_news の category 列挙型の .describe() ですべてカバーされているため、ツールのみを使用するクライアントでも機能が失われることはありません。
• 株価、ニュース、決算などのライブデータは、時間の経過により古くなるため、意図的にリソースとして公開していません。データの鮮度はツールのみで提供されます。

機能

@cyanheads/mcp-ts-core を基盤としており、stdio と Streamable HTTP トランスポート、差し替え可能な認証（none / jwt / oauth）、差し替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレースに対応した構造化ロギングを備えています。

Finnhub 固有の機能：

• レート制限に対応した単一の Finnhub クライアント — トークンはサーバー側で注入されます（ツール入力として渡されることはありません）。60 req/min の無料プランに合わせてタイムアウトと再試行が調整されています。
• 株価情報と市場のリアルタイム状況を組み合わせており、市場が閉まっている場合は、リアルタイム価格ではなく前回の終値として報告します。
• サービス境界でステータスを分類します。403 → 明確な not_us_or_paid ドメインエラー、401 → 初回呼び出し時に重大な設定エラーとして報告（「データなし」にはしません）、429/5xx → 再試行します。
• finnhub_get_company はプロフィール、指標、同業他社の情報を並行して取得し、いずれかの処理に失敗した場合は部分的な結果を返します。

エージェントに適した出力：

• 欠損をそのまま扱います。すべてのファンダメンタルデータは null 許容で、存在しない値は null のままです。Finnhub の情報が少ない銘柄もそのまま提示し、ゼロで埋めたり捏造したりしません。
• 「利用不可」を表すシグナルは 2 種類あります。symbol_not_found（未知の米国ティッカー。すべてゼロの株価情報／空のプロフィールというセンチネルから検出）と、not_us_or_paid（海外銘柄または有料プラン限定、HTTP 403）です。これにより、エージェントは両者を区別して対処できます。
• すべての失敗に、復旧のヒントを含む型付きエラーコントラクトがあります。また、isLikelyUS 検索ヒューリスティックにより、エージェントは無料プランで利用できる可能性の高い銘柄を優先できます。
• 件数に上限のあるリストでは、合計件数と切り捨ての有無を示すため、エージェントは追加データの有無を把握できます。

はじめに

このサーバーには無料の Finnhub API キー が必要です（ダッシュボード → API キー）。無料プランでは、米国株式をリアルタイムで 60 req/min まで利用できます。

各ユーザーは自身の API キーを取得する必要があります。利用は Finnhub の利用規約 に従います。無料プランは個人利用のみを対象としており、Finnhub のデータを再配布したり、第三者と共有したりするには、Finnhub の書面による承認が必要です。

以下を MCP クライアントの設定ファイルに追加してください。

{
  "mcpServers": {
    "finnhub-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/finnhub-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "FINNHUB_API_KEY": "your-api-key"
      }
    }
  }
}

または npx を使用する場合（Bun は不要です）：

{
  "mcpServers": {
    "finnhub-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/finnhub-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "FINNHUB_API_KEY": "your-api-key"
      }
    }
  }
}

または Docker を使用する場合：

{
  "mcpServers": {
    "finnhub-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "FINNHUB_API_KEY=your-api-key",
        "ghcr.io/cyanheads/finnhub-mcp-server:latest"
      ]
    }
  }
}

Streamable HTTP の場合は、トランスポートを設定してサーバーを起動します。

MCP_TRANSPORT_TYPE=http MCP_SESSION_MODE=stateless MCP_HTTP_PORT=3010 FINNHUB_API_KEY=... bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以降（または Node.js v24 以降）。
• 無料の Finnhub API キー。無料プランは米国株式のみが対象で、リアルタイム、60 req/min です。海外銘柄（.TO や .DE など、取引所サフィックス付きのティッカー）およびローソク足／外国為替のエンドポイントは有料プラン限定で、明確なエラーが返されます。

インストール

1. リポジトリをクローンします：

git clone https://github.com/cyanheads/finnhub-mcp-server.git

2. ディレクトリに移動します：

cd finnhub-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env and set FINNHUB_API_KEY

設定

すべての設定は、起動時に src/config/server-config.ts の Zod スキーマで検証されます。主な環境変数：

変数	説明	デフォルト
FINNHUB_API_KEY	必須。 finnhub.io/register から取得できる無料の Finnhub API キーです。token クエリパラメーターとして送信され、設定されていない場合、サーバーは起動に失敗します。	—
FINNHUB_BASE_URL	Finnhub REST API のベース URL です。ローカルテストやプロキシ向けに上書きできます。	https://finnhub.io/api/v1
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_HTTP_ENDPOINT_PATH	MCP サーバーをマウントする HTTP エンドポイントのパスです。	/mcp
MCP_SESSION_MODE	セッション処理：auto、stateful、または stateless。サーバーは src/index.ts で stateless を宣言しているため、変数が未設定の場合はそこで解決されます。.env.example と Docker イメージでも明示的に設定されています。明示的に設定された環境変数の値が優先されます。	stateless
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（RFC 5424）：debug、info、notice、warning、error。	info
LOG_TOOL_FAILURE_PAYLOADS	失敗したツール呼び出しの引数と結果をログに記録します。キー名による秘匿化を行い、LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（デフォルトは 16384）でサイズを制限します。自由形式の値に含まれるシークレットは秘匿化されません。	false
STORAGE_PROVIDER_TYPE	ストレージバックエンド：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	OpenTelemetry instrumentation（スパン、メトリクス、完了ログ）を有効にします。	false
OTEL_EXPORTER_OTLP_ENDPOINT	トレース（/v1/traces）とメトリクス（/v1/metrics）の OTLP ベース URL です。シグナル固有のエンドポイントが設定されている場合は、そちらが優先されます。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	オプトイン方式の OTLP ログエンドポイントです。指定した値がそのまま使用されます。ベース URL を設定してもログのエクスポートは有効になりません。	—

省略可能な上書き設定の全一覧は .env.example を参照してください。

サーバーの実行

ローカル開発

• ビルドして実行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• チェックとテストを実行：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t finnhub-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=http -e FINNHUB_API_KEY=your-key -p 3010:3010 finnhub-mcp-server

Dockerfile のデフォルトは、HTTP トランスポート、ステートレスセッションモード、および /var/log/finnhub-mcp-server へのログ出力です。OpenTelemetry のピア依存関係はデフォルトでインストールされます。省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイントです。ツール／リソースを登録し、Finnhub サービスを初期化します。
src/config	サーバー固有の環境変数を解析し、Zod で検証します。
src/mcp-server/tools	ツール定義（*.tool.ts）です。シンボル、株価、企業、決算、ニュース、推奨情報に関する 6 つのツールがあります。
src/mcp-server/resources	リソース定義（*.resource.ts）です。ニュースカテゴリーのリファレンスを提供します。
src/services/finnhub	Finnhub REST クライアントです。認証、型付きエンドポイントメソッド、リトライ、HTTP ステータスの分類を行います。
tests/	src/ に対応するユニットテストと統合テストです。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md ／ AGENTS.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックで try/catch は使用しません。
• リクエストスコープのログには ctx.log を、テナントスコープのストレージには ctx.state を使用します。
• 新しいツールとリソースは、src/mcp-server/*/definitions/index.ts のバレル経由で登録します。
• Finnhub API は、未加工データの検証 → ドメイン型への正規化 → 出力スキーマの返却の順にラップします。存在しないフィールドを決して捏造しないでください。

貢献

課題の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。