stackexchange-mcp-server

---

概要

Super UserやServer FaultからUnix & Linuxまで、Stack OverflowをはじめとするStack Exchangeネットワークを利用できます。質問を検索し、Q&Aスレッド全体を整形されたMarkdownで読み、タグのFAQを閲覧して、ユーザープロフィールを検索できます。

ツール

ツール	説明
stackexchange_search_questions	Stack Exchangeのサイト全体から、全文検索クエリ、タグフィルター、スコアのしきい値、並べ替え順を指定して質問を検索します
stackexchange_get_thread	質問と回答をMarkdownとして取得します。回答数の上限を指定でき、承認済みの回答が先頭になります
stackexchange_get_tag_faq	タグに関する、回答済みで最も高評価の質問を取得します。「Xに関するベストアンサー」の代表的なリストです
stackexchange_get_user	IDでユーザープロフィールを取得します。評判、バッジ数、回答スコア上位のタグ、アカウントのメタデータを確認できます
stackexchange_list_sites	Stack Exchangeネットワークの全サイトと、それぞれのapi_site_parameter値を列挙します

---

機能リファレンス

stackexchange_search_questions _ツール

• 任意のタグフィルター、最小スコアのしきい値、承認済みの質問のみを対象とするフィルターを指定した全文検索に対応しています。関連度（デフォルト）、投票数、アクティビティ、新着順で並べ替えられます
• 1ページあたり最大30件（デフォルトは10件）を取得できます。続きはpageで指定します。各ページの取得でAPIクォータを1ユニット消費し、25ページを超えるページングにはSTACKEXCHANGE_API_KEYが必要です
• 質問ID、タイトル、スコア、回答数、タグ、約300文字の抜粋を返します。IDはそのままstackexchange_get_threadに渡せます
• すべての応答で、残りのクォータと最大クォータをエンリッチメントとして表示します

---

stackexchange_get_thread _ツール

• 数値の質問 ID または Stack Exchange の質問 URL 全体を受け取り、質問と maxAnswers 件の回答（1～100、デフォルトは 10）を含むページを取得します。承認済みの回答がそのページに含まれていない場合は追加します
• HTML から Markdown への正規化を組み込み済みです。コードブロック、リンク、リスト、見出し、引用はすべて変換されます
• 任意の includeComments を指定すると、投稿ごとに新しい順で最大 20 件のコメントを取得します（API 呼び出しが 2 回追加されます。回答がない場合は 1 回）。一部のみ取得されたリストは commentsTruncated で示されます
• CC BY-SA 4.0 に基づき、すべての回答に著者名、プロフィールリンク、スコアが表示されます
• 残りのクォータと最大クォータはエンリッチメントを通じて表示されます。上流に maxAnswers を超える回答がある場合は truncated で示されます

---

stackexchange_get_tag_faq _ツール

• タグに関する、回答済みで最も高い評価を得た質問を取得します。/tags/{tag}/faq に対応する、正規の「X でのベストアンサー」リストです
• 1 ページあたり最大 30 件（デフォルトは 10 件）を取得します。続きは page を指定します。各ページの取得には API クォータを 1 単位消費し、25 ページを超えるには STACKEXCHANGE_API_KEY が必要です
• 本文を含まない質問リストを返します。完全な内容を取得するには、任意の questionId を stackexchange_get_thread に渡してください
• すべてのレスポンスで、残りのクォータと最大クォータがエンリッチメントを通じて表示されます

---

stackexchange_get_user _ツール

• userId は 2,147,483,647 以下（32 ビット）である必要があります。通常は stackexchange_get_thread の出力に含まれる authorUserId を使用します
• 上流 API を 2 回呼び出して、プロフィールと人気タグを取得します
• 信用度、バッジ数（金・銀・銅）、所在地、ウェブサイト、回答数と質問数、回答スコア順の上位タグ最大 10 件を返します（回答がないユーザーの場合は空の配列）
• 不明なユーザー ID には、型付きの user_not_found エラーを返します。Stack Exchange は 404 ではなく、結果が空の状態で HTTP 200 を返します

---

stackexchange_list_sites _ツール

• Stack Exchange ネットワーク内のすべてのサイトを取得します。1 ページ 100 件で、最大 10 ページまで取得します。ネットワークにまだ続きがある場合は、エンリッチメント通知で部分的なリストであることを示します
• 任意の大文字小文字を区別しない名前フィルターを指定すると、サイト名と api_site_parameter に対して照合します。取得後、クライアント側で適用されます
• 他のすべてのツールの site パラメーターで受け付けられる api_site_parameter の値（例：stackoverflow、superuser、serverfault）を返します

---

機能

@cyanheads/mcp-ts-core を基盤とし、stdio と Streamable HTTP のトランスポート、切り替え可能な認証（none／jwt／oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、OpenTelemetry トレースを任意で利用できる構造化ログを提供します。

Stack Exchange 固有の機能：

• HTML から Markdown への変換では、コードブロック、表、リンク、画像、入れ子のリストが保持されます
• 共有の上流キューが、レスポンスのバックオフと HTTP 429 のクールダウンを処理します。各操作には、キュー待ち時間、バックオフ、リクエスト、再試行を含む 50 秒の時間制限があります
• クォータのログ記録：すべてのツール呼び出しで、quota_remaining と quota_max がエンリッチメントを通じて表示されます
• すべてのツールで型付きエラー契約を提供します。invalid_site、invalid_parameter、invalid_api_key、invalid_id_or_url、invalid_user_id、question_not_found、user_not_found、paging_depth_limit、quota_exceeded、upstream_unavailable
• STACKEXCHANGE_API_KEY を任意で指定すると、OAuth を必要とせず、IP ごとのクォータが約 300 件／日から約 10,000 件／日に増えます

エージェントに使いやすい出力：

• すべてのレスポンスに残りのクォータを含めます。エージェントはサーバーを失敗させずにレート制限を考慮した計画を立てられます
• 承認済みの回答を先頭に表示し、その後に残りの回答をスコア順で並べます
• 各回答に CC BY-SA 4.0 に基づく帰属表示を含めます
• 質問やユーザーが見つからない場合は、型付きの not_found エラーを返します（SE は 404 ではなく、items[] が空の状態で HTTP 200 を返します）

---

はじめに

公開ホストインスタンス

公開インスタンスは https://stackexchange.caseyjhand.com/mcp で利用できます。インストールは不要です。Streamable HTTP を提供しており、クライアントごとに設定形式が異なります。

Claude Code の場合：

claude mcp add --transport http stackexchange-mcp-server https://stackexchange.caseyjhand.com/mcp

Cline の場合（cline_mcp_settings.json）：

{
  "mcpServers": {
    "stackexchange-mcp-server": {
      "type": "streamableHttp",
      "url": "https://stackexchange.caseyjhand.com/mcp"
    }
  }
}

Cursor の場合（mcp.json）：

{
  "mcpServers": {
    "stackexchange-mcp-server": {
      "url": "https://stackexchange.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop では、「設定」→「コネクター」からリモートサーバーを追加できます。

セルフホスト／ローカル

以下を MCP クライアントの設定ファイルに追加します。

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

または、npx を使用します（Bun は不要です）。

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

または、Docker を使用します。

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

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

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

レート制限： Stack Exchange API では、キーなしの場合、IP ごとに 1 日あたり約 300 件のリクエストが許可されます。env に STACKEXCHANGE_API_KEY を設定すると、これを 1 日あたり約 10,000 件に増やせます。stackapps.com/apps/oauth/register でキーを登録してください（OAuth フローが必要なのは書き込みアクセスの場合のみです。読み取り専用での利用にはキーだけで十分です）。

前提条件

• Bun v1.4.0 以上（または Node.js v24+）
• STACKEXCHANGE_API_KEY は任意ですが、継続的に利用する場合は強く推奨します

インストール

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

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

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

cd stackexchange-mcp-server

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

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env and set STACKEXCHANGE_API_KEY if desired

---

設定

変数	説明	デフォルト
STACKEXCHANGE_API_KEY	任意。Stack Exchange API キーです。IP ごとの割り当てを 1 日あたり約 300 件から約 10,000 件に増やします。	—
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_HTTP_HOST	HTTP サーバーのホスト。	127.0.0.1
MCP_SESSION_MODE	HTTP セッションモード：auto、stateful、または stateless。auto は stateful に解決されます。意味のある環境変数の値は、このサーバーの stateless というソースのデフォルトを上書きします。空欄、または置換されていないプレースホルダーの場合は、ソースのデフォルトが使われます。	stateless
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（RFC 5424）。	info
LOGS_DIR	ログファイルのディレクトリ（Node.js のみ）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	失敗した各ツール呼び出しの引数と結果をログに記録します。キー名に基づいて機密情報をマスキングし、LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（デフォルトは 16384）で上限を設定します。自由記述の値に含まれるシークレットはマスキングされません。	false
STORAGE_PROVIDER_TYPE	ストレージバックエンド。	in-memory
OTEL_ENABLED	OpenTelemetry インストルメンテーション（スパン、メトリクス、完了ログ）を有効にします。	false
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	OTLP ログのエクスポートをオプトインで有効にします（例：http://localhost:4318/v1/logs）。ベースの OTEL_EXPORTER_OTLP_ENDPOINT を設定しても有効にはなりません。	—

任意の上書き設定の一覧は .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 stackexchange-mcp-server .
docker run --rm -e STACKEXCHANGE_API_KEY=your-key -p 3010:3010 stackexchange-mcp-server

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

---

プロジェクト構成

パス	役割
src/index.ts	createApp() エントリーポイント。ツールを登録し、サービスを初期化します。
src/config/	Zod を使った、サーバー固有の環境変数（STACKEXCHANGE_API_KEY）の解析。
src/mcp-server/tools/	ツール定義（*.tool.ts）。
src/services/stackexchange/	Stack Exchange API v2.3 の HTTP クライアント、バックオフ追跡、割り当てログ、HTML→Markdown 正規化。
tests/	Vitest の単体テストと統合テスト。
docs/	設計ドキュメントとディレクトリツリー。

---

開発ガイド

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

• ハンドラーで例外をスローし、フレームワークで捕捉します。ツールのロジックでtry/catchは使用しません
• リクエストスコープのログ記録にはctx.logを、テナントスコープのストレージにはctx.stateを使用します
• 新しいツールは、src/mcp-server/tools/definitions/index.tsのバレル経由で登録します
• 外部API呼び出しはラップします。生データを検証し、ドメイン型に正規化してから、出力スキーマに従って返します。不足しているフィールドを捏造してはいけません

---

貢献

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

bun run devcheck
bun run test

---

ライセンス

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