Skip to main content
Glama

카우치베이스 MCP 서버

LLM이 Couchbase 클러스터와 직접 상호 작용할 수 있도록 하는 Couchbase의 MCP 서버 구현입니다.

특징

  • 지정된 버킷의 모든 범위 및 컬렉션 목록을 가져옵니다.

  • 컬렉션의 구조를 얻으세요

  • 지정된 범위 및 컬렉션에서 ID로 문서 가져오기

  • 지정된 범위 및 컬렉션에 ID로 문서를 업서트합니다.

  • 지정된 범위 및 컬렉션에서 ID로 문서 삭제

  • 지정된 범위에서 SQL++ 쿼리 실행

    • MCP 서버에는 기본적으로 true로 설정된 READ_ONLY_QUERY_MODE 옵션이 있는데, 이 옵션은 데이터 또는 기본 컬렉션 구조를 변경하는 SQL++ 쿼리 실행을 비활성화합니다. 단, 문서는 ID로 계속 업데이트할 수 있습니다.

Related MCP server: Couchbase MCP Server

필수 조건

  • Python 3.10 이상.

  • 실행 중인 Couchbase 클러스터입니다. 시작하는 가장 쉬운 방법은 Couchbase 서버의 완전 관리형 버전인 Capella 무료 티어를 사용하는 것입니다. 지침 에 따라 샘플 데이터세트 중 하나를 가져오거나 직접 가져올 수 있습니다.

  • 서버를 실행하기 위해 uv가 설치되었습니다.

  • Claude Desktop과 같은 MCP 클라이언트를 설치하여 서버를 Claude에 연결합니다. Claude Desktop과 Cursor에 대한 지침이 제공됩니다. 다른 MCP 클라이언트도 사용할 수 있습니다.

구성

저장소를 로컬 컴퓨터에 복제합니다.

지엑스피1

MCP 클라이언트를 위한 서버 구성

이는 Claude Desktop, Cursor, Windsurf Editor와 같은 MCP 클라이언트의 일반적인 구성입니다.

{
  "mcpServers": {
    "couchbase": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/cloned/repo/mcp-server-couchbase/",
        "run",
        "src/mcp_server.py"
      ],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password",
        "CB_BUCKET_NAME": "bucket_name"
      }
    }
  }
}

환경 변수를 사용하여 서버를 구성할 수 있습니다. 지원되는 변수는 다음과 같습니다.

  • CB_CONNECTION_STRING : Couchbase 클러스터에 대한 연결 문자열

  • CB_USERNAME : 버킷에 접속할 수 있는 사용자 이름

  • CB_PASSWORD : 연결할 사용자 이름의 비밀번호

  • CB_BUCKET_NAME : 서버가 액세스할 버킷의 이름

  • READ_ONLY_QUERY_MODE : 데이터 수정을 허용하는 SQL++ 쿼리의 허용 여부를 설정합니다. 기본적으로 True로 설정됩니다.

  • path/to/cloned/repo/mcp-server-couchbase/ 로컬 컴퓨터의 복제된 저장소 경로여야 합니다. 맨 마지막에 슬래시를 넣는 것을 잊지 마세요!

참고: 클라이언트에서 다른 MCP 서버를 사용 중인 경우 기존 mcpServers 개체에 추가할 수 있습니다.

클로드 데스크탑

Claude Desktop MCP 클라이언트와 함께 Couchbase MCP 서버를 사용하려면 아래 단계를 따르세요.

  1. 이제 구성 파일을 편집하여 Claude Desktop에 MCP 서버를 추가할 수 있습니다. 자세한 내용은 MCP 빠른 시작 가이드를 참조하세요.

    • Mac에서는 구성 파일이 ~/Library/Application Support/Claude/claude_desktop_config.json 에 있습니다.

    • Windows에서는 구성 파일이 %APPDATA%\Claude\claude_desktop_config.json 에 있습니다.

    구성 파일을 열고 mcpServers 섹션에 구성을 추가합니다.

  2. 변경 사항을 적용하려면 Claude Desktop을 다시 시작하세요.

  3. 이제 Claude Desktop의 서버를 사용하여 자연어를 사용하여 Couchbase 클러스터에서 쿼리를 실행하고 문서에 대한 CRUD 작업을 수행할 수 있습니다.

클로드 데스크톱 로그

Claude Desktop의 로그는 다음 위치에서 찾을 수 있습니다.

  • MacOS: ~/라이브러리/로그/클로드

  • 윈도우: %APPDATA%\Claude\Logs

로그는 연결 문제나 MCP 서버 구성 관련 기타 문제를 진단하는 데 사용할 수 있습니다. 자세한 내용은 공식 문서를 참조하세요.

커서

Cursor와 함께 Couchbase MCP 서버를 사용하려면 아래 단계를 따르세요.

  1. 컴퓨터에 커서를 설치하세요.

  2. 커서에서 커서 > 커서 설정 > MCP > 새 글로벌 MCP 서버 추가로 이동하세요. 커서에서 MCP 서버 구성을 설정하는 방법도 참조하세요.

  3. 동일한 구성을 지정하세요. mcpServers라는 상위 키 아래에 서버 구성을 추가해야 할 수도 있습니다.

  4. 구성을 저장합니다.

  5. MCP 서버 목록에 Couchbase가 추가된 서버로 표시됩니다. 서버가 활성화되어 있는지 확인하려면 새로 고침하세요.

  6. 이제 Cursor에서 Couchbase MCP 서버를 사용하여 자연어로 Couchbase 클러스터를 쿼리하고 문서에 대한 CRUD 작업을 수행할 수 있습니다.

Cursor와 MCP 통합에 대한 자세한 내용은 공식 Cursor MCP 문서를 참조하세요.

커서 로그

커서 하단 패널에서 "출력"을 클릭하고 드롭다운 메뉴에서 "커서 MCP"를 선택하면 서버 로그를 볼 수 있습니다. 이를 통해 연결 문제나 MCP 서버 구성 관련 문제를 진단하는 데 도움이 될 수 있습니다.

윈드서핑 편집자

Windsurf Editor 와 함께 Couchbase MCP 서버를 사용하려면 아래 단계를 따르세요.

  1. 컴퓨터에 Windsurf Editor를 설치하세요.

  2. Windsurf 편집기에서 명령 팔레트 > Windsurf MCP 구성 패널 또는 Windsurf - 설정 > 고급 > 캐스케이드 > 모델 컨텍스트 프로토콜(MCP) 서버로 이동합니다. 구성에 대한 자세한 내용은 공식 문서를 참조하세요.

  3. '서버 추가'를 클릭한 다음 '사용자 지정 서버 추가'를 클릭합니다. 편집기에서 열리는 구성에서 위에서 설정한 Couchbase MCP 서버 구성을 추가합니다.

  4. 구성을 저장합니다.

  5. 고급 설정의 MCP 서버 목록에 Couchbase가 추가된 서버로 표시됩니다. 서버가 활성화되어 있는지 확인하려면 새로 고침하세요.

  6. 이제 Windsurf Editor에서 Couchbase MCP 서버를 사용하여 자연어로 Couchbase 클러스터를 쿼리하고 문서에 대한 CRUD 작업을 수행할 수 있습니다.

Windsurf Editor와 MCP 통합에 대한 자세한 내용은 공식 Windsurf MCP 문서를 참조하세요.

SSE 서버 모드

MCP 서버를 SSE(Server-Sent Events) 전송 모드로 실행하는 옵션이 있습니다.

용법

기본적으로 MCP 서버는 포트 8080에서 실행되지만 FASTMCP_PORT 환경 변수를 사용하여 구성할 수 있습니다.

uv run src/mcp_server.py --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 클라이언트에서 사용할 수 있습니다.

도커 이미지

MCP 서버는 Docker 컨테이너로도 빌드하고 실행할 수 있습니다. 미리 빌드된 이미지는 DockerHub 에서 찾을 수 있습니다.

docker built -t mcp/couchbase .

달리기

MCP 서버는 Couchbase 설정을 구성하는 데 사용되는 환경 변수와 함께 실행될 수 있습니다. 환경 변수는 구성 섹션 에서 설명한 것과 동일합니다.

docker run -i \
  -e CB_CONNECTION_STRING='<couchbase_connection_string>' \
  -e CB_USERNAME='<database_user>' \
  -e CB_PASSWORD='<database_password>' \
  -e CB_BUCKET_NAME='<bucket_name>' \
  -e MCP_TRANSPORT='stdio/sse' \
  -e READ_ONLY_QUERY_MODE="true/false" \
  mcp/couchbase

LLM과 관련된 위험

  • 대규모 언어 모델이나 이와 유사한 기술을 사용하면 부정확하거나 유해한 출력이 나올 가능성을 포함한 위험이 따릅니다.

  • Couchbase는 이러한 출력의 품질이나 정확성을 검토하거나 평가하지 않으며, 이러한 출력은 Couchbase의 견해를 반영하지 않을 수 있습니다.

  • 대규모 언어 모델 및 관련 기술을 사용할지 여부를 결정하고, 동일한 기술의 사용을 규정하는 모든 라이선스 조건, 이용 약관 및 조직의 정책을 준수하는 것은 전적으로 귀하의 책임입니다.

관리형 MCP 서버

Couchbase MCP 서버는 Smithery.ai 를 통해 에이전트 애플리케이션에서 관리되는 서버로도 사용할 수 있습니다.

문제 해결 팁

  • 구성에서 MCP 서버 저장소 경로가 올바른지 확인하세요.

  • Couchbase 연결 문자열, 데이터베이스 사용자 이름, 비밀번호 및 버킷 이름이 올바른지 확인하세요.

  • Couchbase Capella를 사용하는 경우 MCP 서버가 실행 중인 컴퓨터에서 클러스터에 액세스할 수 있는지 확인하세요.

  • 데이터베이스 사용자에게 지정된 버킷에 액세스할 수 있는 적절한 권한이 있는지 확인하세요.

  • uv 패키지 관리자가 제대로 설치되고 접근 가능한지 확인하세요. 설정 파일의 command 필드에 uv의 절대 경로를 입력해야 할 수도 있습니다.

  • MCP 서버 관련 문제를 나타낼 수 있는 오류나 경고가 있는지 로그를 확인하세요. 서버 로그는 mcp-server-couchbase.log 라는 이름으로 저장됩니다.


📢 지원 정책

이 프로젝트에 관심을 가져주셔서 진심으로 감사드립니다!
이 프로젝트는 커뮤니티에서 유지 관리되는 프로젝트이므로 당사 지원팀에서 공식적으로 지원하지 않습니다 .

도움이 필요하거나 버그를 발견했거나 개선에 기여하고 싶다면 바로 여기, GitHub 이슈를 여는 것이 가장 좋습니다.
당사 지원 포털에서는 이 프로젝트와 관련된 요청을 지원할 수 없으므로, 모든 문의는 GitHub 내에서만 접수해 주시기 바랍니다.

여러분의 협력 덕분에 우리 모두가 함께 앞으로 나아갈 수 있게 되었습니다. 감사합니다!

Available Tools

36 tools
discover_tool_input_valuesA
Read-only

Find the exact input values a specific tool requires, from reference data bundled with this server.

Call this BEFORE calling a tool that needs an exact identifier you do not already know. Do not guess the identifier and do not browse the Couchbase documentation website for it -- a guessed value comes back from the target tool as an error with no data. The reference data ships inside this server, so this works offline and while the cluster is unreachable, which is exactly when you are most likely to be looking up a metric name.

Registered today:

  • tool_name="get_cluster_metrics" -> every Couchbase Server metric name, with its type (counter/gauge/histogram), unit, the server version it first appeared in, and a one-line description. Feed a result's "name" straight into get_cluster_metrics.

tool_name is the only required argument; everything else is optional.

Two ways to call it:

  1. Browse -- pass tool_name alone. Every registered dataset is currently treated as too large to list in full, so this returns "record_count", a small "sample_records" preview, the "chapters" block (the small set of fields you can filter on, with every legal value and a record count each), and a "next_step" pointing you at search instead of a partial list.

  2. Search -- pass tool_name and search_keywords. Returns records ranked by fuzzy relevance, best first. Matching is fuzzy over identifiers and descriptions, so partial words and near-misses still hit.

Every response includes the chapters block, so you never need a separate browse call before narrowing.

Inputs: tool_name (required), min_score, max_results, chapter_filters, +1 more. Returns: object

explain_sql_plus_plus_queryA
Read-only

Generate and evaluate an EXPLAIN plan for a SQL++ query. It provides information about the execution plan for the query.

The EXPLAIN statement is run in the specified scope in the specified bucket. It returns query metadata along with an extracted plan and plan evaluation.

Inputs: query (required), scope_name (required), bucket_name (required). Returns: object

get_active_queriesA
Read-only

Get all queries executing right now, across every query-service node.

Use this to find a runaway or stuck statement: elapsed time, the statement text, the client, and current state. Pair with get_cluster_query_vitals to confirm the engine is actually under load from what this returns, and pass a result's "requestId" to delete_active_query to cancel it.

Calls GET /admin/active_requests. Self-managed Couchbase Server 7.6+ only (Capella is rejected without a REST call); needs at minimum the Read-Only Admin (ro_admin) role — verify against your cluster's RBAC before relying on this in production.

/admin/active_requests answers per node — a request only shows up when the node running it is asked — so every query-service node is queried and the lists are merged into one. Each entry already carries its own "node" field, so there is no need to tag entries by which endpoint answered.

Returns {"status": "success", "active_requests": [...merged...], "unreachable_nodes": [{"node", "error"}]} (the last key omitted when every node answered), or {"status": "error", "error": ...} if no query node could be reached at all, or the cluster is Capella.

Inputs: timeout. Returns: object

get_bucket_configA
Read-only

Get a bucket's configuration and live state — or every bucket's, if bucket_name is omitted.

Answers "what is this bucket configured as, and how full is it right now?" — RAM quota, replica count, eviction policy, durability level, storage backend, conflict- resolution type, auto-compaction settings, and basic stats (item count, memory used, ops/sec, disk used). Use this to explain a bucket-level symptom that get_cluster_metrics or get_index_stats pointed at, or as a pre-flight safety check before advising a compaction/quota/durability change — this tool only ever reads; create/edit/flush/delete stay CAO-owned. get_buckets_in_cluster lists bucket names via the SDK but exposes none of this; use this tool once a specific bucket needs explaining.

bucket_name must be omitted (not passed as "") to get every bucket — an empty string is rejected rather than silently treated the same as omitting it, since a caller that meant to name a bucket should not get back every bucket's configuration instead.

Calls GET /pools/default/buckets/<bucket_name> (one bucket) or GET /pools/default/buckets (every bucket, when bucket_name is omitted). Self-managed Couchbase Server 7.6+ only (Capella is rejected without a REST call); needs the Read-Only Admin (ro_admin) role.

Reading the result — returned exactly as the endpoint sends it, nothing stripped or renamed, so every field keeps its REST API name (camelCase):

  • "autoCompactionSettings" is the bare value false, not an object, when the bucket has no per-bucket override. Read false as "uses the cluster-wide compaction settings", not "compaction disabled" — they are not the same thing, and this field alone cannot tell you which.

  • "durabilityMinLevel" and "storageBackend" are absent on server versions that predate those fields; absence means "not reported", not "none"/"couchstore".

  • "vBucketServerMap" and "nodes" are the bulk of the payload (a full server list and a per-vBucket map that grows with vbucket/replica/node count) and carry no RCA-relevant signal, but are not stripped: this tool never reshapes what the endpoint returns.

  • A node that was never joined to a cluster (or whose cluster-init failed) answers this endpoint with 200 and [] rather than an error. This is unlikely to matter for a connection_string naming hosts an operator verified are cluster members, but is a real risk when it names a DNS/SRV record backed by a rotating node set (e.g. a Kubernetes headless service), where a connection can land on a freshly provisioned, not-yet-joined node: an empty list there is not proof the cluster itself has no buckets.

Returns the endpoint's response unchanged — a dict for one bucket, a list for all buckets. Raises on failure, including a 404 for an unknown bucket name.

Inputs: timeout, bucket_name. Returns: result

get_buckets_in_clusterA
Read-only

Get the names of all the accessible buckets in the cluster.

Inputs: no named parameters. Returns: result

get_client_connectivity_reportA
Read-only

Check whether the client's connections were already broken, and for how long.

Unlike get_cluster_health_and_services (which actively pings each service right now), this reports the SDK's own cached connection state without performing any network I/O. It's cheap enough to call frequently, but it's only as fresh as the last time the SDK actually talked to each node — it won't proactively detect a service that just went down if nothing has touched it since. Use get_cluster_health_and_services instead when you need a live, right-now reachability check; there's also no way to filter this report to specific services the way that tool's ping can, since no I/O means nothing to filter.

For each known endpoint, reports which service it belongs to, its remote/local addresses, connection state, and last_activity — how long it's been since that connection last saw traffic. Also reports an overall online/degraded/offline cluster state.

This call makes no request to the server at all, so it needs no specific RBAC role beyond whatever the initial cluster connection already required — unlike an active ping, it isn't gated on KV/Query/Search or Cluster Admin privileges.

Returns:

  • Diagnostics report with per-endpoint connection state and overall cluster state

Inputs: no named parameters. Returns: object

get_cluster_health_and_servicesA
Read-only

Check whether the cluster is reachable right now, and where it's broken.

This actively pings (see caveat below) the cluster's services and reports, per service:

  • Whether it responded and how long it took (latency)

  • Which node/endpoint answered, and any error if it didn't

Scope: cluster-level vs bucket-level ping

  • If bucket_name is omitted, this pings at the cluster level. This covers more services in one call, but whether the key-value (KV) service is included depends on the Couchbase Server version — it may be silently skipped.

  • If bucket_name is provided, this pings from the perspective of that bucket instead. This guarantees the KV service is covered for that bucket, but the result is scoped to that one bucket only — ping again per bucket_name to cover a multi-bucket cluster.

service_types optionally restricts which services get pinged. Valid values: "key_value", "query", "search", "analytics", "view", "management", "eventing". Omit to ping every service. An unrecognized value returns an error response instead of raising.

Caution — this is somewhat invasive: unlike a passive connection-state check, ping performs a live network round-trip to every targeted service. Prefer a narrow service_types filter, and avoid calling this in tight loops or high-frequency polling.

Returns:

  • Cluster health status with service-level connection details and latency measurements

Inputs: bucket_name, service_types. Returns: object

get_cluster_health_snapshotA
Read-only

Get per-node service topology, membership, orchestrator and health in one call.

Use this to turn a symptom into a specific node and service: which node is in "warning", what it runs, whether it is still in the cluster, and whether it is the orchestrator — i.e. whether acting on it is disruptive. Also answers "did a topology change leave us in a good state?" after a node replacement or failover.

Self-managed Couchbase Server 7.6+ only (Capella is rejected without a REST call); needs the Read-Only Admin (ro_admin) role.

Reading the result:

  • cluster.unhealthy_nodes / inactive_nodes are the fast path: a node is in unhealthy_nodes when status is not "healthy", and in inactive_nodes when it is no longer an "active" member (e.g. "inactiveFailed" — already failed over, which is a different situation from an active node merely reporting "warning").

  • safe_to_act_on is false only for the orchestrator, where a restart or failover is disruptive in a way it is not elsewhere. When cluster.orchestrator_known is false no node could be flagged, so read safe_to_act_on as "unknown", not "yes" — the cluster reports no orchestrator while one is being elected.

  • reachable_address is the address to probe next, chosen between the node's internal and externally advertised addresses based on which one this server reached the cluster on. Probing the other form may fail for network reasons that look like a node outage; alternateAddresses keeps it as a fallback.

  • cluster.counters holds lifetime rebalance tallies: rebalance_start above rebalance_success means a rebalance began and did not finish — the signature of an interrupted topology change. Pair with get_cluster_tasks for what is running now.

  • recoveryType other than "none" means a recovery is in progress: not healthy yet, rather than broken.

Returns {"cluster": {...}, "nodes": [...]}; raises on failure.

Inputs: timeout. Returns: object

get_cluster_metricsA
Read-only

Get one or more cluster statistics over a historic time window in a single call.

Use this to quantify a suspected problem (e.g. after get_cluster_health_and_services or get_client_connectivity_report) — is a metric spiking, climbing, or stable over time?

Self-managed Couchbase Server 7.6+ only — rejects Capella connections without a REST call. Calls POST /pools/default/stats/range.

metrics is passed through as the request body: a list of specs, each with a required "metric" (list of {"label", "value"} pairs, e.g. [{"label": "name", "value": "kv_ep_diskqueue_fill"}]), an optional "nodes" ("host:port" targets; omit it to cover every node, which is usually what you want), and optional "applyFunctions", "nodesAggregation", "start"/"end" (negative seconds relative to now; default -60/now), "step" (seconds, default 10), "alignTimestamps".

To find metric names, call discover_tool_input_values(tool_name="get_cluster_metrics") — it lists or searches the full Couchbase metrics reference bundled with this server, offline. Don't guess a metric name: an unknown name comes back as a per-spec error with no data.

Not bounded: any number of specs, window, step, or node count is passed straight through to the REST call, so a broad request (long window, fine step, many nodes/specs) can return a large response.

Returns {"status": "success", "data": [...]} (one entry per spec, each with "data" and any per-spec "errors") or {"status": "error", "error": "..."}.

Inputs: metrics (required), timeout. Returns: object

get_cluster_query_vitalsA
Read-only

Get query-engine health (vitals) from every query-service node.

Distinguishes "the workload is heavy" from "the query engine itself is stressed" — get_cluster_metrics covers node hardware; this covers the N1QL service layer specifically: request rate, active/queued request counts, memory, GC, service uptime. Use it after get_cluster_metrics/ get_cluster_health_snapshot show healthy infra but queries are still slow.

Calls GET /admin/vitals. Self-managed Couchbase Server 7.6+ only (Capella is rejected without a REST call); needs at minimum the Read-Only Admin (ro_admin) role — verify against your cluster's RBAC before relying on this in production, since the N1QL Admin API's exact privilege requirements are not fully documented.

/admin/vitals answers per node, not cluster-wide — each query node only describes itself — so every query-service node is queried and the results are keyed by node ("host:port").

Returns {"status": "success", "vitals": {"host:port": {...}, ...}, "unreachable_nodes": [{"node", "error"}]} (the last key omitted when every node answered), or {"status": "error", "error": ...} if no query node could be reached at all, or the cluster is Capella.

Inputs: timeout. Returns: object

get_cluster_system_eventsA
Read-only

Get the cluster's system event log — what changed on the cluster, and when.

This is the RCA timeline: once a symptom is confirmed, it finds the config change, failover, rebalance or service restart that preceded it. Window it to the symptom's onset with since_time, then cross-check that timestamp against get_cluster_metrics.

Self-managed Couchbase Server 7.6+ only (Capella is rejected without a REST call); needs the Full Admin or Cluster Admin role. Calls GET /events.

Ordering — easy to misread:

  • Events are ALWAYS oldest-first, but which ones the server picks depends on since_time. Without it, the server takes the limit MOST RECENT events, so the last element is the newest thing on the cluster. With it, it takes the limit EARLIEST events at or after that time, so the last element is NOT the newest — more may follow it.

  • Do not re-sort or re-slice to get "the latest N": slicing keeps the oldest. Lower limit and let the server choose.

  • To page forward, pass summary.next_since_time as the next since_time. It is inclusive, so the boundary event repeats — dedupe on uuid. When it is null on a truncated result, check summary.paging_blocked: every event in the batch shares one timestamp, so sinceTime cannot move past them and a higher limit is the only way to see the rest.

A cluster's log is overwhelmingly "info", so expect routine entries in the window; move the window rather than raising limit.

Reading the result:

  • summary.by_severity / by_component say what the window holds at a glance, so a lone "error" among routine entries is visible without reading every event.

  • summary.possibly_truncated means the server filled the limit, so more events probably exist outside the window. Absence of a later event is not evidence.

  • The log is a ring buffer (10,000 entries by default), so an empty result for an old since_time can mean the events aged out, not that nothing happened.

Returns {"summary": {...}, "events": [...]}; raises on failure.

Inputs: limit, timeout, since_time. Returns: object

get_cluster_tasksA
Read-only

Get the cluster tasks running right now — rebalance, compaction, XDCR, index build.

Answers "what is this cluster doing?" — where stuck rebalances, hung index builds and lagging XDCR surface. One call is a single sample, so pair it with get_cluster_metrics to tell "slow but progressing" from "flatlined".

Calls GET /pools/default/tasks. Self-managed Couchbase Server 7.6+ only (Capella is rejected without a REST call); needs the Read-Only Admin (ro_admin) role.

Returns the endpoint's array unchanged, or [] if no tasks are reported. Only "type" and "status" are common to every entry; the rest are per type — rebalance: progress, perNode, detailedProgress, stageInfo, subtype; bucket_compaction: bucket, progress, changesDone, totalChanges; xdcr: changesLeft, docsChecked, docsWritten, source, target; global_indexes/indexer: bucket, index, progress, id; loadingSampleBucket: task_id, bucket, bucket_uuid.

Reading the result:

  • An idle cluster still reports a rebalance entry with status "notRunning", so check each task's "status" rather than counting entries.

  • "statusIsStale": true means the cluster cannot vouch for that status — read it as "unknown", not "stuck". Flatlined progress and a status that stopped updating look identical here but mean different things.

  • "progress" means different things per type, so do not compare it across tasks.

  • Poll no faster than "recommendedRefreshPeriod" (seconds), the server's own hint.

  • "cancelURI"/"lastReportURI" are informational UI links; this tool only ever GETs and never invokes them.

Inputs: timeout. Returns: result

get_collections_in_scopeA
Read-only

Get the names of all collections in the given scope and bucket.

Inputs: scope_name (required), bucket_name (required). Returns: result

get_document_by_idA
Read-only

Get a document by its ID from the specified scope and collection. If the document is not found, it will raise an exception.

Inputs: scope_name (required), bucket_name (required), document_id (required), collection_name (required). Returns: object

get_index_advisor_recommendationsB
Read-only

Get index recommendations from Couchbase Index Advisor for a given SQL++ query.

The Index Advisor analyzes the query and provides recommendations for optimal indexes. This tool works with SELECT, UPDATE, DELETE, or MERGE queries. The queries will be run on the specified scope in the specified bucket.

Returns a dictionary with:

  • current_used_indexes: Array of currently used indexes (if any)

  • recommended_indexes: Array of recommended secondary indexes (if any)

  • recommended_covering_indexes: Array of recommended covering indexes (if any)

Each index object contains:

  • index: The CREATE INDEX SQL++ command

  • statements: Array of statement objects with the query and run count

Raises an error carrying the advisor's message if the advisor cannot analyse the statement (for example, a SQL++ syntax error).

Inputs: query (required), scope_name (required), bucket_name (required). Returns: object

get_index_statsA
Read-only

Get per-index statistics (size, fragmentation, scan traffic) from the Index Service.

Names which index is responsible for disk or memory pressure — use it after get_cluster_metrics shows a node's index disk climbing.

Filters are hierarchical: scope requires bucket, collection requires both, index requires all three. No filters returns every index in the cluster.

Returns nodes (keyed by node, each with an indexer block and an indexes list of bucket/scope/collection/name + stats), nodes_without_index (nodes that answered but do not hold the requested index — expected, since an index lives only where it was placed) and nodes_failed (nodes that could not be reached, so a partial answer is visible as one). indexer is None for filtered calls.

Numbers are per node. A partitioned index appears under several nodes, each reporting only its own share: sum items_count/data_size/disk_size across nodes, but not num_requests, which every hosting node counts in full.

Reading the stats: disk_size far above data_size (see frag_percent) means space reclaimable by compaction; num_requests with last_known_scan_time (Unix ns, 0 = never) identifies unused indexes; num_docs_pending is indexing lag. Counters reset when the indexer restarts, so a low count alone does not prove an index is unused.

skip_empty=True drops zero-valued fields (~two thirds on an idle cluster) — leave it False when hunting unused indexes, since it also removes num_requests: 0.

Inputs: index_name, scope_name, skip_empty, bucket_name, +1 more. Returns: object

get_longest_running_queriesA
Read-only

Get the N longest running queries from the system:completed_requests catalog.

Prefer this over writing a raw system:completed_requests query via run_sql_plus_plus_query.

Inputs: limit. Returns: result

get_most_frequent_queriesA
Read-only

Get the N most frequent queries from the system:completed_requests catalog.

Prefer this over writing a raw system:completed_requests query via run_sql_plus_plus_query.

Inputs: limit. Returns: result

get_queries_not_selectiveA
Read-only

Get queries that are not very selective from the system:completed_requests catalog.

Prefer this over writing a raw system:completed_requests query via run_sql_plus_plus_query.

Inputs: limit. Returns: result

get_queries_not_using_covering_indexA
Read-only

Get queries that don't use a covering index from the system:completed_requests catalog.

Prefer this over writing a raw system:completed_requests query via run_sql_plus_plus_query.

Inputs: limit. Returns: result

get_queries_using_primary_indexA
Read-only

Get queries that use a primary index from the system:completed_requests catalog.

Prefer this over writing a raw system:completed_requests query via run_sql_plus_plus_query.

Inputs: limit. Returns: result

get_queries_with_large_result_countA
Read-only

Get queries with the largest result counts from the system:completed_requests catalog.

Prefer this over writing a raw system:completed_requests query via run_sql_plus_plus_query.

Inputs: limit. Returns: result

get_queries_with_largest_response_sizesA
Read-only

Get queries with the largest response sizes from the system:completed_requests catalog.

Prefer this over writing a raw system:completed_requests query via run_sql_plus_plus_query.

Inputs: limit. Returns: result

get_schema_for_collectionA
Read-only

Get the schema for a collection in the specified scope. Returns a dictionary with the collection name and the schema returned by running INFER query on the Couchbase collection.

num_sample_values sets how many example values INFER reports per field. Leave it unset to use the server's own default (5). Pass 0 to omit sample values entirely, keeping only the structure and type information.

Inputs: scope_name (required), bucket_name (required), collection_name (required), num_sample_values. Returns: object

get_scopes_and_collections_in_bucketA
Read-only

Get the names of all scopes and collections in the bucket. Returns a dictionary with scope names as keys and lists of collection names as values.

Inputs: bucket_name (required). Returns: object

get_scopes_in_bucketA
Read-only

Get the names of all scopes in the given bucket.

Inputs: bucket_name (required). Returns: result

get_search_index_definitionA
Read-only

Get the full definition of a single Search (FTS) index.

Pass both bucket_name and scope_name together to look up a scope-level (scoped) index in that scope, or omit both to look up a cluster-level ("legacy") index. Passing only one of the two is invalid — Couchbase allows the same index name to exist in different scopes, so the location must be stated explicitly rather than guessed.

Returns {"success": True, "name", "source_type", "idx_type", "source_name", "uuid", "params" (mapping/analyzer configuration), "source_uuid", "source_params", "plan_params" (num replicas/partitions), "bucket", "scope"}. If no index with this name exists at the given location, returns {"success": False, "error": ...} — confirm the exact name and location first with list_search_indexes.

Inputs: index_name (required), scope_name, bucket_name. Returns: object

get_server_configuration_statusA
Read-only

Get the server status and configuration without establishing connection. This tool can be used to verify if the server is running and check the configuration.

Inputs: no named parameters. Returns: object

list_indexesA
Read-only

List indexes in the cluster with optional filtering by bucket, scope, collection, and index name.

Filters must be provided hierarchically: scope requires bucket, collection requires both, index requires all three. Set return_raw_index_stats=True to get the unprocessed source row for each index.

Each result contains: name, definition (CREATE INDEX statement), status, isPrimary, bucket, scope, collection, lastScanTime, is_vector (True for a Hyperscale or Composite Vector Index), and, only when is_vector is True, vector_type ("hyperscale" or "composite"). If a required field is missing, the entry contains warning and raw_index_stats instead.

Source depends on cluster version: v8+ queries system:indexes via the query service (RBAC-scoped — the connected user sees only indexes on keyspaces they can access); older clusters fall back to the admin-level Index Service REST API /getIndexStatus.

Inputs: index_name, scope_name, bucket_name, collection_name, +1 more. Returns: result

list_search_indexesA
Read-only

List Search (FTS) indexes, optionally filtered by bucket and scope.

Filtering behavior:

  • No filters: lists cluster-level ("legacy") Search indexes only — the original, pre-scoped FTS index model, defined at the cluster level.

  • bucket_name only: lists scope-level (scoped) Search indexes across every scope in that bucket.

  • bucket_name and scope_name: lists scope-level Search indexes in that one scope only.

  • scope_name without bucket_name is invalid — returns an error entry explaining that bucket_name is required.

Each entry contains: name, uuid, source_name, source_type, idx_type, bucket, scope. bucket/scope are None for cluster-level (legacy) entries. This is a summary view — to get one index's full definition (mappings, analyzers, plan params), call get_search_index_definition with that entry's name and its own bucket/scope values (both, for a scoped entry; neither, when they're None). Don't reuse this call's filters: listing by bucket_name alone spans several scopes, and get_search_index_definition rejects a bucket without a scope.

Inputs: scope_name, bucket_name. Returns: result

lookup_subdocumentA
Read-only

Look up parts of a document without fetching the whole thing, using Couchbase sub-document operations. Use this instead of get_document_by_id when you only need a few fields, a presence check, or the size of an array/object inside a document — AND you already know the exact field path(s) to look up (e.g. from a prior get_document_by_id call on this same document, from the user explicitly naming the field, or from a known/confirmed schema for this collection).

IMPORTANT: Do NOT guess field paths. If you don't already know the document's exact field names/structure, call get_document_by_id first (or instead) — a guessed path that doesn't exist returns a per-path error here rather than the real data, and reporting "not found" for a wrong guess is worse than just fetching the whole document and reading the right field.

Provide one or more of the following. Each is a list of sub-document paths using Couchbase's dot/bracket path syntax (e.g. "address.city", "tags[0]", "tags[-1]" for the last array element):

  • get_paths: fetch the VALUE at each path.

  • exists_paths: check whether each path exists, without fetching its value (cheaper than get_paths — no payload transfer — when you only need a yes/no answer).

  • count_paths: get the number of elements in the array or object at each path (fails per-path if the path isn't an array/object).

At least one of get_paths, exists_paths, or count_paths must be provided. As a rule of thumb, keep the combined number of paths across all three to 16 or fewer — Couchbase limits subdocument operations per call, though the exact limit is server-side and may change. If the server rejects the call (too many paths, or another constraint like path length or nesting depth), the whole call fails with {"error": "..."}.

A path that doesn't exist (or otherwise fails, e.g. count on a non-array/object) does NOT fail the whole call — it is reported individually as {"error": ...} in the returned dict so the other requested paths can still be resolved.

Returns a dict with a key for each category that was requested (only requested categories are included): { "get": {"": {"value": } | {"error": "..."}}, "exists": {"": {"value": true | false} | {"error": "..."}}, "count": {"": {"value": } | {"error": "..."}}, } On a connection/lookup failure, or an invalid request (no paths / too many paths), returns {"error": ""} instead.

Inputs: scope_name (required), bucket_name (required), document_id (required), collection_name (required), +3 more. Returns: object

run_sql_plus_plus_queryA

Run a SQL++ query on a scope and return the results as a list of JSON values.

The query will be run on the specified scope in the specified bucket. The query should use collection names directly without bucket/scope prefixes, as the scope context is automatically set.

Use named_parameters to bind values to $name placeholders in the query instead of concatenating user input into the statement. This prevents SQL++ injection

Example: query = "SELECT * FROM users WHERE age > 18" # Incorrect: "SELECT * FROM bucket.scope.users WHERE age > 18"

For creating a new index (scalar or vector), prefer the create_query_index tool over a raw CREATE INDEX statement here — it defers the build by default and tells you the recommended next step. Use list_indexes to check whether an index is online before relying on it in a query plan.

For relevance-scored, fuzzy, or linguistic full-text search (scoring, highlighting, faceting, fuzzy/phrase/wildcard matching), prefer run_search over SQL++'s SEARCH() function — it keeps FTS-specific result shape (score, fragments, facets) out of general query results and gives clearer tracing of what was searched.

Inputs: query (required), scope_name (required), bucket_name (required), named_parameters. Returns: result

run_vector_queryA
Read-only

Embed a query and run a vector similarity search against a GSI vector index.

Embedding: query_text is embedded using the model configured via CB_MCP_EMBEDDING_MODEL_PROVIDER/CB_MCP_EMBEDDING_MODEL/CB_MCP_EMBEDDING_MODEL_API_KEY/CB_MCP_EMBEDDING_MODEL_ENDPOINT (plus CB_MCP_EMBEDDING_MODEL_AWS_* for provider=bedrock). If no provider is configured, this tool returns {"success": False, "error": ...} explaining what to set -- it is not hidden from tool discovery when unconfigured.

Index selection: this tool queries a Couchbase 8.0+ GSI vector index (Composite Vector Index or Hyperscale Vector Index) via SQL++'s APPROX_VECTOR_DISTANCE(). Unlike Search-service vector search, GSI selects the index automatically from the vector field referenced in the query -- there is no index_name parameter, and none is needed.

distance_metric is required, deliberately with no default: it must match the similarity the index was created with (CREATE INDEX ... WITH {"similarity": ...}), or Couchbase silently falls back to not using the Composite/Hyperscale Vector Index at all (no error -- the query still returns correct results, just unindexed). There is no one value that's usually right, since it depends entirely on how the specific index was created, and this tool has no index_name to look that up automatically (see above) -- call list_indexes first and read the similarity value out of the matching index's definition field (valid values: cosine, dot, l2/euclidean, l2_squared/euclidean_squared).

num_probes/rerank/top_n_scan are Hyperscale Vector Index tuning parameters. num_probes (integer) is the number of centroids to probe -- raise it to improve poor recall. rerank (true/false) re-checks the top candidates against the full vectors; it needs num_probes. top_n_scan (integer) is how many candidates to rerank; it needs num_probes and rerank. num_probes alone, or num_probes + rerank, are both valid. A Composite Vector Index doesn't use any of them. This tool itself has no index_name to check, but list_indexes now reports each index's vector_type ("hyperscale" or "composite") -- check that first if you need to know which shape will actually serve the query.

where is an optional raw SQL++ boolean expression (e.g. "doc.status = 'active'") appended to prefilter candidates before the vector ordering -- this tool only ever emits a SELECT, so, unlike run_sql_plus_plus_query, there is no write-guard for it to bypass. If the index was created with a partial-index condition (create_query_index's condition), where must match or imply it for the planner to actually use that index -- otherwise it falls back to a full scan silently (confirmed via EXPLAIN), the same footgun documented above for a mismatched distance_metric.

select_fields limits the projected document fields; omit it to return the full document. limit defaults to 10, matching the other query/search tools in this server.

Returns {"success": True, "hits": [{"id", "distance", "document": {... selected fields, or the full document}}], "total_hits", "cluster_major_version", and a "warning" key only when the detected cluster major version is below 8 (informational -- a pre-8.0 cluster fails the query naturally with its own "unknown function" error rather than being blocked here)} or {"success": False, "error": ...}. The document is nested under "document" rather than merged into the hit directly -- a document field literally named "id" or "distance" would otherwise silently collide with (and could overwrite) this tool's own id/distance metadata.

Inputs: query_text (required), scope_name (required), bucket_name (required), vector_field (required), +8 more. Returns: object

test_cluster_connectionA
Read-only

Test the connection to Couchbase cluster and optionally to a bucket. This tool verifies the connection to the Couchbase cluster and bucket by establishing the connection if it is not already established. If bucket name is not provided, it will not try to connect to the bucket specified in the MCP server settings. Returns connection status and basic cluster information.

Inputs: bucket_name. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 36 tools

    Disambiguation4/5

    Most tools target clearly distinct resources/actions, and the descriptions do heavy lifting to separate read-only KV, SQL++, FTS, vector, index, and cluster-ops surfaces. A few pairs are genuinely easy to confuse: run_vector_query (GSI) vs run_vector_search (FTS), get_scopes_and_collections_in_bucket vs get_scopes_in_bucket/get_collections_in_scope, and the three cluster-health tools (health_and_services, health_snapshot, client_connectivity_report). The six query-analysis tools are individually named but form a dense cluster an agent must read carefully.

    Naming Consistency4/5

    Names are uniformly snake_case and almost all follow verb_noun (get_, list_, run_, explain_, discover_, test_). Minor deviations: near-duplicate verbs for similar concepts (get_document_by_id vs lookup_subdocument, run_vector_query vs run_vector_search) which read consistently but blur intent. No camelCase or style mixing.

    Tool Count2/5

    36 tools exceeds the 25+ threshold and the surface spans many domains (KV, SQL++, FTS, vector, indexes, cluster diagnostics). Several query-analysis tools (not_selective, not_using_covering_index, using_primary_index, large_result_count, largest_response_sizes, longest_running, most_frequent) could be consolidated into a single parameterized tool. The count feels heavy relative to what an agent can reliably pick from.

    Completeness3/5

    The read/investigation surface is broad and strong, but there are no document write tools (no insert/upsert/replace/delete) despite the server being KV-capable. Several tools reference operations that aren't in the surface: run_sql_plus_plus_query points to create_query_index, and get_active_queries points to delete_active_query — neither exists, creating dead-end references. Read-only by design, but the stated domain (a Couchbase MCP server) implies write/lifecycle coverage that's missing.

    Maintenance

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables large language models to interact directly with MongoDB databases, allowing them to query collections, inspect schemas, and manage data through natural language.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A server that enables natural language interactions with Couchbase databases through the Model Context Protocol, allowing users to perform SQL++ queries on Couchbase Capella clusters using conversational commands.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that enables large language models to interact directly with Couchbase databases through natural language, supporting operations like querying buckets, performing CRUD operations, and executing N1QL queries.
      33 npm
      7
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server implementation that allows Large Language Models to directly interact with YugabyteDB databases, supporting table listing and read-only SQL queries.
      11
      Apache 2.0

    Appeared in Searches