🚀 🦆 MCP Rubber Duck
MCP(Model Context Protocol)サーバーです。複数のOpenAI互換LLMをクエリするための橋渡し役として機能します。ゴムダックデバッグのように、様々なAI「ダック」に問題を説明し、異なる視点からの回答を得ることができます!

🚀 クイックスタート
npm install -g mcp-rubber-duck
npx mcp-rubber-duck
Claude Desktopを使用していますか? Claude Desktop Configurationにジャンプしてください。
✨ 主な機能
- 🔌 Universal OpenAI Compatibility:任意のOpenAI互換APIエンドポイントで動作します。
- 🦆 Multiple Ducks:複数のLLMプロバイダーを同時に設定し、クエリすることができます。
- 💬 Conversation Management:複数のメッセージにわたってコンテキストを維持します。
- 🏛️ Duck Council:設定したすべてのLLMから一度に応答を得ることができます。
- 🗳️ Consensus Voting:複数のダックによる投票と、理由付きの信頼度スコアを提供します。
- ⚖️ LLM-as-Judge:ダック同士が互いの応答を評価し、ランキングすることができます。
- 🔄 Iterative Refinement:2つのダックが協力して応答を改善します。
- 🎓 Structured Debates:オックスフォード、ソクラテス、対立的な討論形式をサポートします。
- 💾 Response Caching:インテリジェントなキャッシュにより、重複したAPI呼び出しを回避します。
- 🔁 Automatic Failover:主要なプロバイダーが失敗した場合、他のプロバイダーに自動的にフォールバックします。
- 📊 Health Monitoring:すべてのプロバイダーのリアルタイムなヘルスチェックを行います。
- 🔗 MCP Bridge:他のMCPサーバーに接続し、ダックの機能を拡張します。
- 🛡️ Granular Security:セッションベースの承認により、サーバーごとの承認コントロールを行います。
- 🎨 Fun Duck Theme:ゴムダックデバッグを楽しく体験できます!
📦 インストール
前提条件
- Node.js 20以上
- npmまたはyarn
- サポートされているプロバイダーの少なくとも1つのAPIキー
インストール方法
オプション1:NPMからインストール
npm install -g mcp-rubber-duck
オプション2:ソースからインストール
git clone https://github.com/nesquikm/mcp-rubber-duck.git
cd mcp-rubber-duck
npm install
npm run build
npm start
📚 ドキュメント
設定方法
方法1:環境変数を使用
プロジェクトのルートに.envファイルを作成します。
# OpenAI
OPENAI_API_KEY=sk-...
OPENAI_DEFAULT_MODEL=gpt-5.1 # オプション: デフォルトはgpt-5.1
# Google Gemini
GEMINI_API_KEY=...
GEMINI_DEFAULT_MODEL=gemini-2.5-flash # オプション: デフォルトはgemini-2.5-flash
# Groq
GROQ_API_KEY=gsk_...
GROQ_DEFAULT_MODEL=llama-3.3-70b-versatile # オプション: デフォルトはllama-3.3-70b-versatile
# Ollama (Local)
OLLAMA_BASE_URL=http://localhost:11434/v1 # オプション
OLLAMA_DEFAULT_MODEL=llama3.2 # オプション: デフォルトはllama3.2
# Together AI
TOGETHER_API_KEY=...
# カスタムプロバイダー (複数追加可能)
# 形式: CUSTOM_{NAME}_* ここでNAMEはプロバイダーキーになります (小文字)
# 例: プロバイダー "myapi" を追加
CUSTOM_MYAPI_API_KEY=...
CUSTOM_MYAPI_BASE_URL=https://api.example.com/v1
CUSTOM_MYAPI_DEFAULT_MODEL=custom-model # オプション
CUSTOM_MYAPI_MODELS=model1,model2 # オプション: カンマ区切りのリスト
CUSTOM_MYAPI_NICKNAME=My Custom Duck # オプション: 表示名
# 例: プロバイダー "azure" を追加
CUSTOM_AZURE_API_KEY=...
CUSTOM_AZURE_BASE_URL=https://mycompany.openai.azure.com/v1
# グローバル設定
DEFAULT_PROVIDER=openai
DEFAULT_TEMPERATURE=0.7
LOG_LEVEL=info
# MCP Bridge設定 (オプション)
MCP_BRIDGE_ENABLED=true # ダックが外部のMCPサーバーにアクセスできるようにする
MCP_APPROVAL_MODE=trusted # always, trusted, or never
MCP_APPROVAL_TIMEOUT=300 # 秒
# MCP Server: Context7 Documentation (例)
MCP_SERVER_CONTEXT7_TYPE=http
MCP_SERVER_CONTEXT7_URL=https://mcp.context7.com/mcp
MCP_SERVER_CONTEXT7_ENABLED=true
# サーバーごとの信頼されたツール
MCP_TRUSTED_TOOLS_CONTEXT7=* # すべてのContext7ツールを信頼する
# オプション: カスタムダックのニックネーム (楽しんで設定してください!)
OPENAI_NICKNAME="DUCK-4" # オプション: デフォルトは "GPT Duck"
GEMINI_NICKNAME="Duckmini" # オプション: デフォルトは "Gemini Duck"
GROQ_NICKNAME="Quackers" # オプション: デフォルトは "Groq Duck"
OLLAMA_NICKNAME="Local Quacker" # オプション: デフォルトは "Local Duck"
CUSTOM_NICKNAME="My Special Duck" # オプション: デフォルトは "Custom Duck"
注意:ダックのニックネームは完全にオプションです!設定しない場合、魅力的なデフォルト値(GPT Duck、Gemini Duckなど)が使用されます。config.jsonファイルを使用する場合、それらのニックネームは環境変数よりも優先されます。
方法2:設定ファイルを使用
サンプルに基づいてconfig/config.jsonファイルを作成します。
cp config/config.example.json config/config.json
Claude Desktopの設定
これは、Claude DesktopでMCP Rubber Duckを使用する最も一般的な設定方法です。
ステップ1:インストール
以下のオプションから1つを選択してください。
オプションA:NPM(推奨)
npm install -g mcp-rubber-duck
オプションB:ソースから(Installation from Sourceを参照)
ステップ2:Claude Desktopを設定
Claude Desktopの設定ファイルを編集します。
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
MCPサーバーの設定を追加します。
NPMを介してインストールした場合:
{
"mcpServers": {
"rubber-duck": {
"command": "mcp-rubber-duck",
"env": {
"MCP_SERVER": "true",
"OPENAI_API_KEY": "your-openai-api-key-here",
"GEMINI_API_KEY": "your-gemini-api-key-here",
"DEFAULT_PROVIDER": "openai"
}
}
}
}
ソースからインストールした場合:
{
"mcpServers": {
"rubber-duck": {
"command": "node",
"args": ["/absolute/path/to/mcp-rubber-duck/dist/index.js"],
"env": {
"MCP_SERVER": "true",
"OPENAI_API_KEY": "your-openai-api-key-here",
"GEMINI_API_KEY": "your-gemini-api-key-here",
"DEFAULT_PROVIDER": "openai"
}
}
}
}
重要:プレースホルダーのAPIキーを実際のキーに置き換えてください。
your-openai-api-key-here → あなたのOpenAI APIキー(sk-で始まります)
your-gemini-api-key-here → Google AI Studioから取得したGemini APIキー
注意:MCP_SERVER: "true"は必須です。これにより、rubber-duckが任意のMCPクライアントに対してMCPサーバーとして動作するように指示されます(MCP Bridge機能とは関係ありません)。
ヒント:LOG_LEVEL、カスタムモデルのデフォルト値、ダックのニックネームなどの追加オプションについては、Configurationを参照してください。
ステップ3:Claude Desktopを再起動
- Claude Desktopを完全に終了します(Macでは⌘+Q)。
- Claude Desktopを再度起動します。
- MCPサーバーは自動的に接続されるはずです。
ステップ4:統合をテスト
再起動後、Claudeで以下のコマンドをテストしてください。
ダックのヘルスチェック
Use the list_ducks tool with check_health: true
以下のように表示されるはずです。
- ✅ GPT Duck (openai) - Healthy
- ✅ Gemini Duck (gemini) - Healthy
利用可能なモデルをリストする
Use the list_models tool
特定のダックに質問する
Use the ask_duck tool with prompt: "What is rubber duck debugging?", provider: "openai"
複数のダックを比較する
Use the compare_ducks tool with prompt: "Explain async/await in JavaScript"
特定のモデルをテストする
Use the ask_duck tool with prompt: "Hello", provider: "openai", model: "gpt-4"
Claude Desktopの設定のトラブルシューティング
ツールが表示されない場合
- APIキーを確認:APIキーが正しく入力され、タイプミスがないことを確認してください。
- ビルドを検証:
ls -la dist/index.jsを実行して、プロジェクトが正常にビルドされたことを確認してください。
- ログを確認:Claude Desktopの開発者コンソールでエラーを探してください。
- 再起動:設定を変更した後、Claude Desktopを完全に終了して再起動してください。
接続問題
- 設定ファイルのパス:正しい設定ファイルのパスを編集していることを再度確認してください。
- JSON構文:JSON構文を検証してください(末尾のカンマはなく、適切な引用符を使用していること)。
- 絶対パス:
dist/index.jsへの完全な絶対パスを使用していることを確認してください。
- ファイルの権限:Claude Desktopがdistディレクトリを読み取れることを確認してください。
ヘルスチェックが失敗する場合
ダックが不健康と表示される場合:
- APIキー:キーが有効で、十分なクレジット/クォータがあることを確認してください。
- ネットワーク:インターネット接続とファイアウォール設定を確認してください。
- レート制限:一部のプロバイダーは新しいアカウントに対して厳しいレート制限を設定しています。
MCP Bridge - 他のMCPサーバーに接続
MCP Bridgeを使用すると、あなたのダックが他のMCPサーバーのツールにアクセスできるようになり、チャットだけでなく、ドキュメントの検索、ファイルのアクセス、APIのクエリなど、その機能を拡張することができます!
注意:これは上記のMCPサーバーの統合とは異なります。
- MCP Bridge (
MCP_BRIDGE_ENABLED):ダックが外部のMCPサーバーをクライアントとして使用します。
- MCP Server (
MCP_SERVER):Rubber-duckが任意のMCPクライアントに対してMCPサーバーとして動作します。
クイックセットアップ
MCP Bridgeを有効にするには、以下の環境変数を追加します。
MCP_BRIDGE_ENABLED="true"
MCP_APPROVAL_MODE="trusted"
MCP_APPROVAL_TIMEOUT="300"
MCP_SERVER_CONTEXT7_TYPE="http"
MCP_SERVER_CONTEXT7_URL="https://mcp.context7.com/mcp"
MCP_SERVER_CONTEXT7_ENABLED="true"
MCP_TRUSTED_TOOLS_CONTEXT7="*"
承認モード
always:すべてのツール呼び出しに承認が必要です(セッションベースのメモリを持つ)。
- ツールの初回使用時 → 承認が必要。
- 同じツールの後続の使用時 → 自動的に実行されます(再起動まで)。
trusted:信頼されていないツールのみ承認が必要です。
- 信頼されたリストにあるツールは即座に実行されます。
- 未知のツールは承認が必要です。
never:すべてのツールが即座に実行されます(注意して使用してください)。
サーバーごとの信頼されたツール
細かいセキュリティのために、MCPサーバーごとに信頼レベルを設定します。
MCP_TRUSTED_TOOLS_CONTEXT7="*"
MCP_TRUSTED_TOOLS_FILESYSTEM="read-file,list-directory"
MCP_TRUSTED_TOOLS_GITHUB="get-repo-info,list-issues"
MCP_TRUSTED_TOOLS="common-safe-tool"
MCPサーバーの設定
環境変数を使用してMCPサーバーを設定します。
HTTPサーバー
MCP_SERVER_{NAME}_TYPE="http"
MCP_SERVER_{NAME}_URL="https://api.example.com/mcp"
MCP_SERVER_{NAME}_API_KEY="your-api-key"
MCP_SERVER_{NAME}_ENABLED="true"
STDIOサーバー
MCP_SERVER_{NAME}_TYPE="stdio"
MCP_SERVER_{NAME}_COMMAND="python"
MCP_SERVER_{NAME}_ARGS="/path/to/script.py,--arg1,--arg2"
MCP_SERVER_{NAME}_ENABLED="true"
例: Context7 Documentationを有効にする
MCP_BRIDGE_ENABLED="true"
MCP_APPROVAL_MODE="trusted"
MCP_SERVER_CONTEXT7_TYPE="http"
MCP_SERVER_CONTEXT7_URL="https://mcp.context7.com/mcp"
MCP_SERVER_CONTEXT7_ENABLED="true"
MCP_TRUSTED_TOOLS_CONTEXT7="*"
これで、あなたのダックはContext7からドキュメントを検索し、取得することができます。
Ask: "Can you find React hooks documentation from Context7 and return only the key concepts?"
Duck: *searches Context7 and returns focused, essential React hooks information*
トークン最適化の利点
Smart Token Management:ダックはMCPサーバーから包括的なデータを取得できますが、必要な本質的な情報のみを返すことで、ホストLLMの会話でトークンを節約します。
- 具体的な要求をする:"Find TypeScript interfaces documentation and return only the core concepts"
- ダックが完全なドキュメントを処理する:Context7から完全なドキュメントにアクセスします。
- 凝縮された結果を返す:不必要な詳細を除外し、焦点を絞った関連情報を提供します。
- トークンの節約:生のドキュメントのダンプと比較して、応答サイズを70-90%削減します。
例のワークフロー:
You: "Find Express.js routing concepts from Context7, keep it concise"
Duck: *Retrieves full Express docs, processes, and returns only routing essentials*
Result: 500 tokens instead of 5,000+ tokens of raw documentation
セッションベースの承認
alwaysモードを使用する場合、システムはあなたの承認を記憶します。
- 初回:"Duck wants to use
search-docs - Approve? ✅"
- 次回:ダックは自動的に
search-docsを使用します(新しい承認は必要ありません)。
- 別のツール:"Duck wants to use
get-examples - Approve? ✅"
- 再起動:セッションメモリがクリアされ、最初からやり直します。
これにより、セキュリティを維持しながら、承認の疲れを解消することができます!
💻 使用例
基本的な使用法
await ask_duck({
prompt: "Explain async/await in JavaScript"
});
会話
await chat_with_duck({
conversation_id: "learning-session",
message: "What is TypeScript?"
});
await chat_with_duck({
conversation_id: "learning-session",
message: "How does it differ from JavaScript?"
});
応答を比較する
await compare_ducks({
prompt: "What's the best way to handle errors in Node.js?",
providers: ["openai", "groq", "ollama"]
});
Duck Council
await duck_council({
prompt: "Should I use REST or GraphQL for my API?"
});
マルチエージェントの投票
await duck_vote({
question: "Best database for a real-time chat app?",
options: ["PostgreSQL", "MongoDB", "Redis", "Cassandra"]
});
応答を評価する
const responses = await duck_council({
prompt: "Implement a rate limiter"
});
await duck_judge({
responses: responses,
criteria: ["correctness", "efficiency", "readability"],
persona: "senior backend engineer"
});
反復的な改善
await duck_iterate({
prompt: "Write a TypeScript function to deep clone objects",
providers: ["openai", "gemini"],
mode: "critique-improve",
iterations: 3
});
構造化された討論
await duck_debate({
prompt: "Monorepo vs polyrepo for a growing startup",
format: "oxford",
rounds: 3
});
プロバイダー固有の設定
Ollama (Local)
curl -fsSL https://ollama.ai/install.sh | sh
ollama pull llama3.2
LM Studio (Local)
- https://lmstudio.ai/からLM Studioをダウンロードします。
- LM Studioでモデルを読み込みます。
- ローカルサーバーを起動します(localhost:1234/v1にOpenAI互換エンドポイントを提供します)。
Google Gemini
- Google AI StudioからAPIキーを取得します。
- 環境に追加します:
GEMINI_API_KEY=...
- OpenAI互換エンドポイントを使用します(ベータ版)。
Groq
- https://console.groq.com/keysからAPIキーを取得します。
- 環境に追加します:
GROQ_API_KEY=gsk_...
Together AI
- https://api.together.xyz/からAPIキーを取得します。
- 環境に追加します:
TOGETHER_API_KEY=...
OpenAI互換性の検証
プロバイダーがOpenAI互換であるかどうかを確認するには、次の手順を行います。
- そのAPIドキュメントで
/v1/chat/completionsエンドポイントを探します。
- OpenAI SDKをサポートしているかどうかを確認します。
- curlでテストします。
curl -X POST "https://api.provider.com/v1/chat/completions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "model-name",
"messages": [{"role": "user", "content": "Hello"}]
}'
🔧 技術詳細
アーキテクチャ
mcp-rubber-duck/
├── src/
│ ├── server.ts # MCP server implementation
│ ├── config/ # Configuration management
│ ├── providers/ # OpenAI client wrapper
│ ├── tools/ # MCP tool implementations
│ ├── services/ # Health, cache, conversations
│ └── utils/ # Logging, ASCII art
├── config/ # Configuration examples
└── tests/ # Test suites
開発
開発モードで実行
npm run dev
テストを実行
npm test
コードをlintする
npm run lint
型チェックを実行
npm run typecheck
Dockerのサポート
MCP Rubber Duckは、macOS (Intel & Apple Silicon)、Linux (x86_64 & ARM64)、Windows (WSL2)、**Raspberry Pi 3+**で動作するマルチプラットフォームのDockerサポートを提供します。
事前構築済みイメージでのクイックスタート
最も簡単な方法は、事前構築済みのマルチアーキテクチャイメージを使用することです。
docker pull ghcr.io/nesquikm/mcp-rubber-duck:latest
cp .env.template .env
docker compose up -d
プラットフォーム固有のデプロイ
デスクトップ/サーバー (macOS、Linux、Windows)
./scripts/deploy.sh --platform desktop
./scripts/deploy.sh --platform desktop --profile with-ollama
Raspberry Pi
./scripts/deploy.sh --platform pi
cp .env.pi.example .env
docker compose up -d
SSHを介したリモートデプロイ
./scripts/deploy.sh --mode ssh --ssh-host pi@192.168.1.100
汎用デプロイスクリプト
scripts/deploy.shスクリプトは、あなたのプラットフォームを自動検出し、最適な設定を適用します。
./scripts/deploy.sh
./scripts/deploy.sh --help
利用可能なオプション:
--mode:docker(デフォルト)、local、またはssh
--platform:pi、desktop、またはauto(デフォルト)
--profile:lightweight、desktop、with-ollama
--ssh-host:リモートデプロイ用
プラットフォーム固有の設定
Raspberry Pi(メモリ最適化)
# .env.pi.example - Pi 3+向けに最適化
DOCKER_CPU_LIMIT=1.5
DOCKER_MEMORY_LIMIT=512M
NODE_OPTIONS=--max-old-space-size=256
デスクトップ/サーバー(高性能)
# .env.desktop.example - 強力なシステム向けに最適化
DOCKER_CPU_LIMIT=4.0
DOCKER_MEMORY_LIMIT=2G
NODE_OPTIONS=--max-old-space-size=1024
Docker Composeのプロファイル
docker compose up -d
docker compose --profile desktop up -d
docker compose --profile with-ollama up -d
マルチアーキテクチャイメージのビルド
独自のマルチアーキテクチャイメージをビルドして公開したい開発者向けです。
./scripts/build-multiarch.sh --platforms linux/amd64,linux/arm64
./scripts/gh-deploy.sh --public
リモートDockerでClaude Desktopを接続
リモートシステムで実行されているMCP Rubber DuckにClaude Desktopを接続します。
{
"mcpServers": {
"rubber-duck-remote": {
"command": "ssh",
"args": [
"user@remote-host",
"docker exec -i mcp-rubber-duck node /app/dist/index.js"
]
}
}
}
プラットフォーム互換性
| Platform |
Architecture |
Status |
Notes |
| macOS Intel |
AMD64 |
✅ Full |
Via Docker Desktop |
| macOS Apple Silicon |
ARM64 |
✅ Full |
Native ARM64 support |
| Linux x86_64 |
AMD64 |
✅ Full |
Direct Docker support |
| Linux ARM64 |
ARM64 |
✅ Full |
Servers, Pi 4+ |
| Raspberry Pi 3+ |
ARM64 |
✅ Optimized |
Memory-limited config |
| Windows |
AMD64 |
✅ Full |
Via Docker Desktop + WSL2 |
手動のDockerコマンド
docker-composeを使用しない場合は、以下のコマンドを使用できます。
docker run -d \
--name mcp-rubber-duck \
--memory=512m --cpus=1.5 \
--env-file .env \
--restart unless-stopped \
ghcr.io/nesquikm/mcp-rubber-duck:latest
docker run -d \
--name mcp-rubber-duck \
--memory=2g --cpus=4 \
--env-file .env \
--restart unless-stopped \
ghcr.io/nesquikm/mcp-rubber-duck:latest
トラブルシューティング
プロバイダーが機能しない場合
- APIキーが正しく設定されていることを確認してください。
- エンドポイントURLが正しいことを確認してください。
- ヘルスチェックを実行します:
list_ducks({ check_health: true })
- 詳細なエラーメッセージをログで確認してください。
接続問題
- ローカルのプロバイダー(Ollama、LM Studio)の場合は、それらが実行されていることを確認してください。
- ローカルエンドポイントのファイアウォール設定を確認してください。
- クラウドプロバイダーへのネットワーク接続を確認してください。
レート制限
- キャッシュを有効にして、API呼び出しを減らします。
- 代替プロバイダーへのフェイルオーバーを設定します。
max_retriesとtimeout設定を調整します。
コントリビューション
__
<(o )___
( ._> /
`---' Quack! Ready to debug!
🦆 私たちのダックの池をもっと良くする手助けをしたいですか?
私たちはコントリビューションを大歓迎です!バグの修正、機能の追加、ダックに新しい技を教えるなど、あなたが何をしようとも、私たちの群れに参加していただけることを嬉しく思います。
始めるには、Contributing Guideをチェックしてください。私たちは約束します、通常のコントリビューションガイドよりも楽しいです - ダックがいます! 🦆
コントリビューターのクイックスタート:
- リポジトリをフォークします。
- 機能ブランチを作成します。
- conventional commit guidelinesに従ってください。
- 新しい機能に対してテストを追加します。
- プルリクエストを送信します。
📄 ライセンス
MITライセンス - 詳細についてはLICENSEファイルを参照してください。
謝辞
- ゴムダックデバッグ方法にインスパイアされています。
- Model Context Protocol (MCP)上に構築されています。
- 普遍的な互換性のためにOpenAI SDKを使用しています。
変更履歴
CHANGELOG.mdを参照して、変更とリリースの詳細な履歴を確認してください。
レジストリとディレクトリ
MCP Rubber Duckは、複数のチャネルを通じて利用可能です。