MCP Gateway
Integrates multiple MCP servers into a single interface with a management Web UI and real-time status updates.
MCP Gateway
複数のMCPサーバーを統合し、Dockerネットワーク経由でアクセス可能にするゲートウェイ
📋 必要な環境
必須要件
- Node.js: v18以上
- Docker: v20以上（Web UI使用時）
- Docker Compose: v2以上（Web UI使用時）
推奨環境
- OS: macOS、Linux、Windows (WSL2)
- メモリ: 4GB以上の空きRAM
- ストレージ: 1GB以上の空き容量
🎯 特徴
- 複数のMCPサーバーを統合:
obsidian、context7、githubなど複数のMCPサーバーを1つのインターフェースに - Docker間通信: 他のDockerコンテナからMCPツールを実行
- MCP管理用Web UI: ブラウザから簡単にMCPサーバーを管理
- リアルタイム更新: WebSocket経由でステータスをリアルタイム更新
- ツール名の自動変換:
serverName_toolName形式で各サーバーのツールを識別
⚠️ 重要な注意事項
Web UI（http://localhost:3002）でMCPサーバーが「エラー」と表示されるのは正常な動作です。MCPサーバーはClaude Codeから接続された時に初めて起動されます。
状態の説明
- 無効: サーバーが無効化されている
- 接続中... (青色): サーバーへの接続を試行中
- 接続済み (緑色): サーバーに正常に接続されている
- エラー (赤色): 接続に失敗した（詳細なエラー原因が表示されます）
🚀 クイックスタート
統合起動（推奨）
# プロキシサーバーとDockerコンテナを一括起動
npm start
# または
./start.sh
# 一括停止
npm stop
# または
./stop.sh
個別起動
# プロキシサーバーを起動（基本）
bun run start
📌 動作ポート
- プロキシサーバー: ws://localhost:9999
- APIサーバー: http://localhost:3003
- MCP管理用Web UI: http://localhost:3002
🤖 Claude Desktopでの使用
Claude Desktopへの設定
Claude Desktopの設定ファイル（~/Library/Application Support/Claude/claude_desktop_config.json）に以下を追加：
{
"mcpServers": {
"gateway": {
"command": "docker",
"args": ["exec", "-i", "shared-mcp-gateway-server", "bun", "server/index.ts"],
"cwd": "/path/to/mcp-gateway/mcp-proxy-server"
}
}
}
重要:
- Gateway MCPを使用する場合、個別のMCPサーバー（obsidian、context7など）の設定は削除してください
🤖 Claude Codeでの使用
Claude CodeでMCP Gatewayを使用するには、以下の方法があります：
方法1: ローカル実行（推奨）
# 1. プロキシサーバーを起動（別ターミナル）
cd /path/to/mcp-gateway
npm run proxy
# 2. Claude Codeに追加
claude mcp add gateway /path/to/mcp-gateway/start-mcp-for-claude.sh
方法2: Docker経由での実行
# 1. Docker Composeを起動
cd /path/to/mcp-gateway
bun start
# 2. Claude Codeに追加（専用コンテナを使用）
claude mcp add gateway -- docker exec -i shared-mcp-gateway-server bun server/index.ts
注意**:
- Docker経由で実行する場合、プロキシサーバーが起動している必要があります
--を忘れずに付けてください（claude mcp addのオプションとコマンドを区別するため）
🤖 Claude Code（Docker版）でのMCP追加方法
MCPサーバーの追加コマンド
Claude CodeのDockerコンテナ内で、MCP Gatewayを追加するには：
方法1: Docker exec（推奨）
同じDockerネットワーク内のコンテナに接続：
# プロキシサーバーとmcp-gatewayのdockerを起動
cd path/to/mcp-gateway
bun start
# 統合しようとしているdocker-compose.ymlと.envに設定を書き足す
path/to/mcp-gateway/integrate.sh docker-compose.yml
# 統合したdocker-compose.ymlを起動 ※ 必要に応じて読み替えてください
docker compose build
docker compose up -d
# 統合先のコンテナのclaude codeにMCP Gatewayコンテナに接続
claude mcp add gateway -- docker exec -i shared-mcp-gateway-server bun server/index.ts
設定の確認
# 追加されたMCPサーバーを確認
claude mcp list
# 特定のサーバーの詳細を表示
claude mcp get gateway
# サーバーを削除する場合
claude mcp remove gateway
🔧 mcp-config.jsonの設定
mcp-gateway/mcp-config.jsonでMCPサーバーを設定：
{
"servers": {
"obsidian": {
"command": "/path/to/obsidian-mcp-server",
"args": [],
"env": {},
"enabled": true
},
"github": {
"command": "npx",
"args": ["@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
},
"enabled": true
}
}
}
📝 設定ファイル (mcp-config.json)
{
"servers": {
"obsidian": {
"command": "/path/to/obsidian-mcp-server",
"args": [],
"env": {
"OBSIDIAN_API_KEY": "your-api-key"
},
"enabled": true // 有効無効の切り替えで使用
},
"context7": {
"command": "npx",
"args": ["@upstash/context7-mcp"],
"env": {},
"enabled": true // 有効無効の切り替えで使用
}
}
}
🎯 注意事項
プロキシサーバーはBun専用
プロキシサーバー（mcp-proxy-server）はBunランタイムに特化して最適化されています。watch-config.jsはNode.jsで動作します。
環境変数
以下の環境変数を.envファイルで設定できます：
# ポート設定
MCP_PROXY_PORT=9999
MCP_API_PORT=3003
MCP_WEB_PORT=3002
🔧 開発
スクリプト
# プロキシサーバー起動
npm run proxy
# プロキシサーバー起動（設定ファイル監視付き）
npm run proxy:watch
# クリーンアップ
bun run clean
# WebSocket接続の安定性テスト
npm run test:websocket
🛡️ WebSocket接続の安定性向上
実装された改善点
-
自動再接続機能
- 指数バックオフアルゴリズムによる再接続
- 最大5回まで自動的に再接続を試行
- 再接続間隔: 1秒から最大30秒まで段階的に増加
-
Ping/Pongによる健全性チェック
- 30秒ごとに自動的にPingを送信
- 接続の生存確認とレイテンシー測定
- 応答がない場合は自動的に再接続
-
接続プール管理
- 各接続に一意のIDを割り当て
- 5分間アクティビティがない接続は自動クリーンアップ
- 接続状態の詳細な追跡とログ
-
詳細なエラーハンドリング
- エラータイプごとの適切な処理
- ユーザーフレンドリーなエラーメッセージ
- 自動復旧戦略の実装
設定可能なパラメータ
WebSocketTransportのオプション:
reconnectAttempts: 再接続試行回数（デフォルト: 5）reconnectDelay: 初期再接続遅延（デフォルト: 1000ms）maxReconnectDelay: 最大再接続遅延（デフォルト: 30000ms）pingInterval: Ping送信間隔（デフォルト: 30000ms）
📚 アーキテクチャ
Claude Desktop使用時（MCP管理用Web UI付き）
┌─────────────────┐
│ Claude Desktop │
└────────┬────────┘
│ stdio
▼
┌─────────────────┐ ┌──────────────┐
│ Gateway MCP │ │ MCP管理用 │
│ Server │ HTTP API │ Web UI │
│ │◀───localhost:3003──│ localhost │
└────────┬────────┘ │ :3002 │
└──────────────┘
│
WebSocket
ws://localhost:9999
│
┌────────▼────────┐
│ MCP Proxy │
│ Server │
└────────┬────────┘
│
┌────┴────┐
│ spawn │
┌───▼───┐ ┌───▼───┐
│ MCP │ │ MCP │
│Server1│ │Server2│ ・・・
└───────┘ └───────┘
DockerでClaude Code使用時
┌─────────────────────┐ ┌─────────────────────┐ ┌──────────────┐
│ Claude Code │ │ MCP Gateway │ │ MCP管理用 │
│ Container │ │ Container │ │ Web UI │
│ │ │ │ │ localhost │
│ ┌───────────────┐ │ │ ┌───────────────┐ │ │ :3002 │
│ │ Claude Code │──┼──┼─▶│ Gateway MCP │◀─┼────────────┤ │
│ │ │ │ │ │ Server │ │ HTTP API └──────────────┘
│ └───────────────┘ │ │ └───────┬───────┘ │ localhost:3003
│ │ │ │ │
└─────────────────────┘ └──────────┼──────────┘
│
WebSocket
ws://host:9999
│
┌───────────────────────────────────▼────────────┐
│ Host Machine │
│ ┌──────────────────────────────────────────┐ │
│ │ MCP Proxy Server │ │
│ └────────────────────┬─────────────────────┘ │
│ │ │
│ ┌────┴────┐ │
│ │ spawn │ │
│ ┌─────▼─────┐ ┌─────▼─────┐ │
│ │ MCP │ │ MCP │ │
│ │ Server 1 │ │ Server 2 │ ・・・ │
│ └───────────┘ └───────────┘ │
└────────────────────────────────────────────────┘
🔧 トラブルシューティング
ツール数が表示されない場合
- MCPサーバーが正しく起動しているか確認
mcp-config.jsonの設定が正しいか確認- 環境変数（API KEYなど）が設定されているか確認
Dockerコンテナから接続できない場合
- ネットワーク名が正しいか確認:
docker network ls - コンテナ名が正しいか確認:
docker ps - ポートが開いているか確認:
docker port shared-mcp-gateway-server
🔗 Claude-Projectとの統合
既存のClaude-ProjectにMCP Gatewayを統合する場合：
使用方法
./setup-claude-project.sh [Claude-Projectパス] <docker-compose.ymlファイル名>
注意: docker-compose.ymlファイル名は必須です。
使用例
# 基本的な使い方
./setup-claude-project.sh ~/Claude-Project docker-compose-base.yml
# カスタムパス
./setup-claude-project.sh /path/to/project docker-compose.yml
# teams環境用
./setup-claude-project.sh ~/Claude-Project docker-compose-teams.yml
# 開発環境用
./setup-claude-project.sh ~/Claude-Project docker-compose-dev.yml
# カレントディレクトリで実行
./setup-claude-project.sh . docker-compose.yml
スクリプトは以下を自動実行：
- 統合ファイルを指定されたClaude-Projectディレクトリにコピー
- 対話式でセットアップを続行するか確認
- Git Submoduleの追加やDocker設定の作成
詳細はclaude-project-integration/README.mdを参照してください。
Related Servers
Agile Planner MCP Server
An AI-powered server for generating agile artifacts like backlogs, features, and user stories.
CodeGraphContext
An MCP server that indexes local code into a graph database to provide context to AI assistants.
Sequential Thinking Multi-Agent System (MAS)
An MCP agent that utilizes a Multi-Agent System (MAS) for sequential thinking and problem-solving.
MCP-guide
A guide for setting up an MCP server using a Python virtual environment and integrating it with the Cline VS Code extension.
Rails MCP Server
An MCP server for Rails projects, allowing LLMs to interact with your application.
Figma MCP Server with Chunking
An MCP server for the Figma API, with chunking and pagination to handle large files.
Aider MCP Server
An MCP server for offloading AI coding tasks to Aider, enhancing development efficiency and flexibility.
Modes MCP Server
An MCP server for programmatically managing Roo's custom operational modes.
Stata-MCP
Perform regression analysis using Stata with the help of an LLM. Requires a local Stata installation and an external LLM API key.
Authless Remote MCP Server
An authentication-free, remote MCP server designed for deployment on Cloudflare Workers.