Couchbase Guru MCP Server

MCPサーバーで、LLMがMCPクライアントからCouchbaseドキュメントを検索できるようにします。単一のツール ask_couchbase_docs を公開しており、質問をホスト型の検索拡張（RAG）ドキュメントエージェントに転送し、ソースリンク付きの回答を返します。

Couchbaseクラスターや認証情報は不要です。 サーバーはドキュメントエージェントのバックエンドとのみ通信し、あなたのデータにはアクセスしません。

ツール

完全で自己完結した質問を送ってください。バックエンドには会話履歴がないため、関連する場合は製品、バージョン、言語を含めてください（例：「Couchbase Server 7.6でPython SDKを使ってプライマリインデックスを作成するにはどうすればよいですか？」）。

Related MCP server: docrag

前提条件

• Python 3.10以上。

• サーバーを実行するには uv がインストールされていること。

• Claude Desktop、Cursor、VS Code などの MCPクライアント。

設定

サーバーは、ビルド済みのPyPIパッケージから、または uv を使用してソースから実行できます。設定不要で動作し、デフォルトでは公開ドキュメントエージェントが使用されます。

PyPIから実行する

{
  "mcpServers": {
    "couchbase-guru": {
      "command": "uvx",
      "args": ["couchbase-guru"]
    }
  }
}

既に他のMCPサーバーを設定している場合は、このエントリを既存の mcpServers オブジェクトに追加してください。

ソースから実行する

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

git clone https://github.com/Couchbase-Ecosystem/couchbase-guru.git

次に、MCPクライアントからこのサーバーを指定します：

{
  "mcpServers": {
    "couchbase-guru": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/cloned/repo/couchbase-guru/",
        "run",
        "src/mcp_server.py"
      ]
    }
  }
}

path/to/cloned/repo/couchbase-guru/ は、お使いのマシン上のクローンしたリポジトリへのパスに置き換えてください。末尾のスラッシュを忘れないでください。

オプション

すべてのオプションは省略可能で、CLI引数または環境変数で設定できます：

インストールされているバージョンを確認するには：

uvx couchbase-guru --version

ドキュメントエージェントのセルフホスティング

デフォルトでは、サーバーは共有の公開ドキュメントエージェントを使用するため、ほとんどのユーザーはセットアップ不要です。独自のエージェントバックエンドを実行している場合は、そのバックエンドをサーバーに指定します：

uvx couchbase-guru --agent-base-url https://your-agent.example.com

レート制限とプライバシー

公開エージェントはフェアユースに基づくレート制限を適用します。これをサポートするため、サーバーは仮名化されたデバイス識別子をバックエンドに送信します（User-Agent ヘッダー内）。

• stdio: 一度生成されたランダムなIDで、お使いのマシンのユーザーごとのファイルに保存されます。

• HTTP: 接続元IPのソルト付き一方向ハッシュ。生のアドレスが送信されることはありません。

MCPサーバー自体が質問内容や個人データを保存することはありません。レート制限のシグナルを共有したくない場合は、エージェントをセルフホストしてください（上記参照）。

クライアント別の設定

1. 設定ファイルを編集します（MCPクイックスタートガイド を参照）：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. 設定 を mcpServers セクションに追加します。

3. Claude Desktopを再起動します。

ログ：~/Library/Logs/Claude（macOS）または %APPDATA%\Claude\Logs（Windows）。

1. Cursorで、Cursor Settings > Tools & Integrations > MCP Tools に移動します。

2. 設定 を手動で追加するか、ワンクリックの Install in Cursor リンクを使用します。

3. 保存して、更新してサーバーが有効になっていることを確認します。

ログ：下部パネルの Output をクリックし、ドロップダウンから Cursor MCP を選択します。

1. Command Palette > Windsurf MCP Configuration Panel を開きます（または Settings > Advanced > Cascade > Model Context Protocol (MCP) Servers）。

2. Add Server > Add custom server をクリックし、設定 を追加します。

3. 保存して、更新してサーバーが有効になっていることを確認します。

詳細については、Windsurf MCPドキュメント を参照してください。

1. ワークスペースに .vscode/mcp.json を作成します（またはグローバル設定として MCP: Open User Configuration を実行します）。

2. VS Codeはトップレベルのキーとして servers を使用します（mcpServers ではありません）：

   {
     "servers": {
       "couchbase-guru": {
         "command": "uvx",
         "args": ["couchbase-guru"]
       }
     }
   }

3. 保存したら、インラインのアクションリストを使用してサーバーを Start/Stop/管理します。

詳細については、VS Code MCPドキュメント を参照してください。

1. AI Assistant または Junie プラグインをインストールします。

2. Settings > Tools > AI Assistant or Junie > MCP Server に移動します。

3. "+" をクリックし、設定 を追加して、Save をクリックし、次に Apply をクリックします。

ログ：Help > Show Log in Finder (Explorer) > mcp > couchbase-guru。

Streamable HTTPトランスポートモード

サーバーは Streamable HTTP モードで実行できるため、複数のクライアントを1つのインスタンスに接続できます。先に、お使いのMCPクライアントがこのトランスポートをサポートしていることを確認してください。

uvx couchbase-guru --transport=http --port=8000

サーバーは http://localhost:8000/mcp で利用可能になります：

{
  "mcpServers": {
    "couchbase-guru-http": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

このモードには認証サポートは含まれません。

Docker

イメージをビルドします：

docker build -t couchbase-guru .

実行します（デフォルトはstdio。認証情報は不要です）：

{
  "mcpServers": {
    "couchbase-guru-docker": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "couchbase-guru"]
    }
  }
}

HTTPトランスポートの場合は、ポートを公開してトランスポートを設定します：

docker run --rm -i \
  -e CB_MCP_TRANSPORT=http \
  -e CB_MCP_HOST=0.0.0.0 \
  -e CB_MCP_PORT=8000 \
  -p 8000:8000 \
  couchbase-guru

LLMに関連するリスク

• 大規模言語モデルおよび類似のテクノロジーの使用には、不正確または有害な出力の可能性を含むリスクが伴います。

• Couchbaseは、そのような出力の品質や正確性をレビューまたは評価せず、そのような出力がCouchbaseの見解を反映していない場合があります。

• 大規模言語モデルおよび関連テクノロジーを使用するかどうかの判断、ならびに該当するライセンス条項、利用規約、および所属組織のポリシーを遵守する責任は、すべてお客様にあります。

トラブルシューティング

• uv/uvx がインストールされ、PATH に含まれていることを確認してください。command フィールドに uv/uvx への絶対パスを指定する必要がある場合があります。

• 検索がタイムアウトした場合、ドキュメントバックエンドがビジー状態の可能性があります。少し待って再試行してください。

• 公開バックエンドの可能性を排除するには、--agent-base-url を指定して独自のエージェントに対して実行してください。

• リポジトリを更新した後にソースから実行する場合は、uv sync を実行して依存関係を更新してください。

• エラーがないか、MCPクライアントのログ（上記の場所）を確認してください。

テスト

ユニットテストはオフラインで実行されます（バックエンドはモック化されます）：

uv sync --extra dev
uv run pytest tests/

統合テストは、ライブのエージェントバックエンドに対してツールをエンドツーエンドで実行するもので、オプトイン方式です：

CB_MCP_RUN_INTEGRATION=1 uv run pytest tests/test_docs_tools.py

デフォルトでは公開エージェントを使用します。別のバックエンドを対象にするには CB_AGENT_BASE_URL を設定してください。

👩💻 コントリビューション

コントリビューションを歓迎します！バグを報告する、機能をリクエストする、改善に貢献する場合は、GitHub issueを開いて ください。

開発者向けセットアップ（uv による環境、Ruffによるlint/フォーマット、pre-commitフック、プロジェクト構造）については、CONTRIBUTING.md を参照してください。

# Clone and set up
git clone https://github.com/Couchbase-Ecosystem/couchbase-guru.git
cd couchbase-guru

# Install with development dependencies
uv sync --extra dev

# Install pre-commit hooks
uv run pre-commit install

📢 サポートポリシー

このプロジェクトにご関心をお寄せいただきありがとうございます！このプロジェクトはCouchbaseコミュニティによってメンテナンスされており、サポートチームによる公式サポートの対象外です。エンジニアがこのリポジトリを監視・メンテナンスし、ベストエフォートで問題の解決に努めます。お問い合わせはすべてGitHub内でお願いします。