Couchbase MCP Server (TypeScript/Bun Version)

Couchbase MCP Server (TypeScript/Bun Version)

LLM が Couchbase クラスターと直接やり取りできる、Couchbase の MCP サーバー実装です。

機能

ツール

データベース操作

• get_scopes_and_collections：指定したバケット内のすべてのスコープとコレクションを一覧表示します
• get_schema_for_collection：特定のコレクションの構造とスキーマを取得します
• get_document_by_id：指定したスコープとコレクションから、ID でドキュメントを取得します
• upsert_document_by_id：指定したスコープとコレクションで、ID によってドキュメントを作成または更新します
• delete_document_by_id：指定したスコープとコレクションから、ID でドキュメントを削除します
• run_sql_plus_plus_query：指定したスコープで SQL++ クエリを実行します

クエリ分析

• get_detailed_indexes：データベースのインデックスに関する包括的な情報を取得します
• get_detailed_prepared_statements：プリペアドステートメントの詳細情報を表示します
• get_system_vitals：システムの健全性メトリクスを監視します
• get_system_nodes：クラスターのノードに関する情報を表示します
• get_most_expensive_queries：リソース消費量が最も多いクエリを特定します
• suggest_query_optimizations：クエリのパフォーマンス改善に関する推奨事項を取得します
• analyze_document_structure：ドキュメント構造のパターンを分析して把握します
• get_document_type_examples：さまざまなタイプのドキュメント例を表示します
• get_prepared_statements：すべてのプリペアドステートメントを一覧表示します
• get_indexes_to_drop：未使用または冗長なインデックスを特定します
• get_completed_requests：完了したクエリリクエストを表示します
• get_system_indexes：すべてのシステムインデックスを一覧表示します
• get_primary_index_queries：プライマリーインデックスを使用するクエリを特定します
• get_largest_result_count_queries：返される結果数が最も多いクエリを見つけます
• get_largest_result_size_queries：結果サイズが最も大きいクエリを特定します
• get_most_frequent_queries：最も頻繁に実行されるクエリを表示します
• get_longest_running_queries：実行時間が最も長いクエリを特定します
• get_fatal_requests：失敗したクエリリクエストを表示します

ドキュメント管理

• list_documentation：MCP サーバーのツールと機能について、利用可能なドキュメントを一覧表示します
• read_documentation：指定したドキュメント項目を読み取ります
• create_documentation：ツールと機能に関する新しいドキュメント項目を作成します
• delete_documentation：ドキュメント項目を削除します
• sync_documentation：既存のドキュメントを同期して更新します

プレイブック管理

• list_playbooks：データベース操作に利用できるプレイブックを一覧表示します

リソース

• データベース構造リソース：データベース構造の情報にアクセスし、管理します
• スキーマリソース：コレクションのスキーマと検証を扱います
• ドキュメントリソース：ドキュメント操作と CRUD 機能を管理します
• クエリリソース：SQL++ クエリの操作と結果を扱います
• クエリ分析リソース：クエリのパフォーマンスを監視し、最適化します
• ドキュメントリソース：ツールと機能のドキュメントを管理します
• プレイブックリソース：データベース操作のプレイブックを管理し、実行します

セキュリティ機能

• READ_ONLY_QUERY_MODE：SQL++ クエリによるデータ変更を防ぐ設定です。デフォルトで有効になっています
• ID ベースのアクセスによる安全なドキュメント操作
• 機密性の高い認証情報を環境変数で設定

前提条件

• Bun 1.0 以上
• 起動中の Couchbase クラスター。簡単に始めるには、Couchbase サーバーのフルマネージド版である Capella の無料プランを利用してください。手順に沿って、サンプルデータセットのいずれかをインポートするか、独自のデータをインポートできます。
• サーバーを Claude に接続するための MCP クライアント。たとえば、Claude Desktop をインストールしてください。手順では Claude Desktop と Cursor を説明しますが、ほかの MCP クライアントも使用できます。

設定

リポジトリをローカルマシンにクローンします。

git clone https://github.com/yourusername/mcp-server-couchbase-bun.git
cd mcp-server-couchbase-bun

依存関係をインストールします。

bun install

TypeScript プロジェクトをビルドします。

bun run build

サンプルを基に .env ファイルを作成します。

cp .env.example .env
# Edit .env with your Couchbase credentials

MCP クライアント向けサーバー設定

Claude Desktop、Cursor、Windsurf Editor などの MCP クライアント向けの設定です。

{
  "mcpServers": {
    "couchbase-capella-mcp": {
      "command": "bun",
      "args": [
        "/path/to/your/mcp-server-couchbase/dist/index.js",
        "--transport",
        "stdio"
      ],
      "env": {
        "COUCHBASE_URL": "couchbases://your-cluster-url",
        "COUCHBASE_USERNAME": "your-username",
        "COUCHBASE_PASSWORD": "your-password",
        "COUCHBASE_BUCKET": "your-bucket",
        "COUCHBASE_SCOPE": "your-scope",
        "COUCHBASE_COLLECTION": "your-collection",
        "LOG_LEVEL": "debug",
        "DOCS_ENABLED": "true",
        "DOCS_BASE_DIR": "/path/to/your/mcp-server-couchbase/docs",
        "DOCS_FILE_EXT": ".md",
        "PWD": "/path/to/your/mcp-server-couchbase",
        "PATH": "/Users/your-username/.bun/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
      },
      "cwd": "/path/to/your/mcp-server-couchbase"
    }
  }
}

注：すべての /path/to/your/mcp-server-couchbase を、クローンしたリポジトリの実際のパスに置き換えてください。また、環境変数を使用する Couchbase クラスターの情報に合わせて更新してください。

サーバーは環境変数を使用して設定できます。以下の変数がサポートされています。

Couchbase 接続設定

• COUCHBASE_URL：Couchbase クラスターへの接続文字列
• COUCHBASE_USERNAME：接続に使用するバケットへのアクセス権を持つユーザー名
• COUCHBASE_PASSWORD：接続に使用するユーザーのパスワード
• COUCHBASE_BUCKET：サーバーがアクセスするバケット名
• COUCHBASE_SCOPE：バケット内で使用するスコープ
• COUCHBASE_COLLECTION：スコープ内で使用するコレクション
• CN_ROOT：Couchbase 設定のルートディレクトリ（デフォルト：'/usr/src'）

MCP サーバー設定

• MCP_SERVER_NAME：MCP サーバーインスタンスの名前
• MCP_TRANSPORT：使用するトランスポートモード（stdio または sse）
• FASTMCP_PORT：SSE トランスポートモードのポート番号（デフォルト：8080）
• READ_ONLY_QUERY_MODE：データを変更できる SQL++ クエリを許可するかどうかを設定します（デフォルト：true）
• LOG_LEVEL：ログレベル（例："debug"、"info"、"warn"、"error"）

ドキュメント設定

• DOCS_ENABLED：ドキュメント機能の有効化／無効化
• DOCS_BASE_DIR：ドキュメントファイルのベースディレクトリ
• DOCS_FILE_EXT：ドキュメントファイルの拡張子

プレイブック設定

• PLAYBOOKS_ENABLED：プレイブック機能の有効化／無効化
• PLAYBOOKS_BASE_DIR：プレイブックファイルのベースディレクトリ
• PLAYBOOKS_FILE_EXT：プレイブックファイルの拡張子

システム設定

• PWD：MCP サーバーの作業ディレクトリ

サーバーの実行

次のコマンドでサーバーを直接実行できます。

# Development mode (TypeScript directly)
bun run dev

# Production mode (compiled JavaScript)
bun run start

SSE トランスポートモードの場合：

# Development mode (TypeScript directly)
bun run dev:sse

# Production mode (compiled JavaScript)
bun run start:sse

クライアントのセットアップ手順

Claude Desktop、Cursor、Windsurf Editor のセットアップ手順は元の Python 版と同じです。コマンドを uv ではなく bun に変更してください。

SSE サーバーモード

MCP サーバーは、Server-Sent Events（SSE）トランスポートモードで実行できます。

使用方法

デフォルトでは MCP サーバーはポート 8080 で実行されますが、FASTMCP_PORT 環境変数で変更できます。

bun run dist/mcp_server.js --connection-string='<couchbase_connection_string>' --username='<database_username>' --password='<database_password>' --bucket-name='<couchbase_bucket_to_use>' --read-only-query-mode=true --transport=sse

サーバーは http://localhost:8080/sse で利用できます。SSE トランスポートモードに対応した MCP クライアントで使用できます。

LLM に関連するリスク

• 大規模言語モデルや同様のテクノロジーの使用には、不正確または有害な出力が生成される可能性などのリスクが伴います。
• Couchbase は、そのような出力の品質や正確性を確認または評価していません。また、そのような出力は Couchbase の見解を反映していない場合があります。
• 大規模言語モデルや関連テクノロジーを使用するかどうかの判断、およびそれらの使用を規定するライセンス条項、利用規約、組織のポリシーの遵守については、すべてお客様の責任となります。

TypeScript の実装に関する注意事項

この実装には、元の Python バージョンと比べて、次のような利点があります。

1. 型安全性：すべての関数、パラメーター、戻り値が強く型付けされています
2. 開発者エクスペリエンス：自動補完やインラインドキュメントにより、IDE のサポートが向上します
3. パフォーマンス：Bun ランタイムにより、JavaScript／TypeScript アプリケーションで優れたパフォーマンスが得られます

トラブルシューティングのヒント

• 設定で MCP サーバーリポジトリへのパスが正しいことを確認してください。
• Couchbase の接続文字列、データベースのユーザー名、パスワード、バケット名が正しいことを確認してください。
• Couchbase Capella を使用している場合は、MCP サーバーの実行マシンからクラスターにアクセスできることを確認してください。
• データベースユーザーに、指定したバケットへのアクセスに必要な権限があることを確認してください。
• Bun が正しくインストールされ、利用可能であることを確認してください。
• MCP サーバーに問題があることを示すエラーや警告がないか、ログを確認してください。

---

サポートポリシー

このプロジェクトに関心をお寄せいただき、心より感謝いたします。 このプロジェクトはコミュニティによって保守されており、サポートチームによる公式サポートの対象ではありません。

サポートが必要な場合、バグを見つけた場合、または改善への貢献を希望する場合は、こちらのGitHub イシューを作成するのが最適です。 サポートポータルではこのプロジェクトに関するお問い合わせには対応できませんので、すべてのお問い合わせを GitHub 内で行っていただきますようお願いいたします。

皆さまのご協力が、共に前進する力になります。ありがとうございます。