Couchbase-Analytics-MCP

A production-grade Model Context Protocol (MCP) server for the Couchbase Enterprise Analytics service. Exposes the full Analytics API surface as 25 strongly-typed MCP tools, with a built-in GUI console, structured logging, Prometheus metrics, OpenTelemetry tracing, and comprehensive test coverage.

Important: This server targets the Analytics service (Apache AsterixDB engine, SQL++, port 8095) — not the Couchbase Query (N1QL) service. All tools call cluster.analyticsQuery() and /analytics/* REST endpoints exclusively.

---

Feature matrix

Feature	Status
25 MCP tools covering full Analytics API	✅
stdio transport (Claude Desktop)	✅
SSE/HTTP transport (remote agents)	✅
Connection pool (min/max/idle reaper)	✅
JWT + API key auth on SSE endpoint	✅
Structured JSON logging (Pino)	✅
Daily log rotation (pino-roll)	✅
Optional Loki push transport	✅
Prometheus /metrics endpoint	✅
OpenTelemetry traces → Jaeger	✅
/health/live + /health/ready probes	✅
React GUI console at /console	✅
Monaco SQL++ editor	✅
Schema browser (dataverse → dataset tree)	✅
Live tool call inspector	✅
Unit tests (≥90% coverage)	✅
Integration tests (real Couchbase)	✅
E2E tests (Supertest SSE transport)	✅
Docker multi-stage image	✅
Docker Compose (CB + Prometheus + Grafana + Jaeger)	✅
Helm chart	✅
GitHub Actions CI/CD	✅
Architecture docs + ADRs	✅
Operational runbooks	✅

---

Quick start

Prerequisites

• Node.js ≥ 20
• Docker + Docker Compose
• Couchbase Server Enterprise ≥ 7.2 with Analytics service enabled

Local development (Docker Compose)

git clone https://github.com/your-org/couchbase-analytics-mcp
cd couchbase-analytics-mcp

# Copy and edit environment
cp .env.example .env

# Start Couchbase + MCP server + Prometheus + Grafana + Jaeger
docker-compose up -d

# GUI console: http://localhost:3000/console
# Prometheus:  http://localhost:9091
# Grafana:     http://localhost:3001  (admin/admin)
# Jaeger:      http://localhost:16686

Run against an existing Couchbase cluster

npm install

CB_CONNECTION_STRING=couchbase://my-cluster \
CB_USERNAME=Administrator \
CB_PASSWORD=password \
TRANSPORT=stdio \
node packages/mcp-server/dist/index.js

Claude Desktop integration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "couchbase-analytics": {
      "command": "node",
      "args": ["/path/to/couchbase-analytics-mcp/packages/mcp-server/dist/index.js"],
      "env": {
        "CB_CONNECTION_STRING": "couchbase://your-cluster",
        "CB_USERNAME": "Administrator",
        "CB_PASSWORD": "your-password",
        "TRANSPORT": "stdio"
      }
    }
  }
}

---

Environment variables

Variable	Default	Description
CB_CONNECTION_STRING	(required)	couchbase://host or couchbases://host for TLS
CB_USERNAME	(required)	Couchbase RBAC username
CB_PASSWORD	(required)	Couchbase RBAC password
CB_ANALYTICS_PORT	8095	Analytics REST port (18095 for TLS)
CB_ANALYTICS_TLS	false	Enable TLS for REST calls
TRANSPORT	stdio	stdio or sse
PORT	3000	HTTP server port (SSE + health + GUI)
POOL_MIN	2	Minimum pool connections
POOL_MAX	10	Maximum pool connections
POOL_IDLE_TIMEOUT_MS	30000	Idle connection reap threshold
QUERY_DEFAULT_TIMEOUT_MS	60000	Default query timeout
LOG_LEVEL	info	trace|debug|info|warn|error|fatal
LOG_FORMAT	json	json|pretty
LOG_FILE_ENABLED	false	Enable file transport
LOG_FILE_PATH	/var/log/cba-mcp/server.log	Log file path
LOKI_HOST	(optional)	Loki push endpoint
METRICS_ENABLED	true	Expose /metrics
OTEL_ENABLED	false	Enable OpenTelemetry tracing
JAEGER_ENDPOINT	http://localhost:14268/api/traces	Jaeger HTTP collector
JWT_SECRET	(optional)	JWT signing secret for SSE auth
API_KEY	(optional)	Static API key for SSE auth
GUI_ENABLED	true	Serve GUI at /console

---

Tool reference

See docs/api/TOOLS.md for full input/output schemas.

Tool	Group	Description
analytics_execute	Query	Execute SQL++ statement
analytics_explain	Query	Return query execution plan
analytics_cancel	Query	Cancel running query
analytics_query_status	Query	Check async query status
analytics_pending_mutations	Query	KV→Analytics replication lag
analytics_list_dataverses	Schema	List all dataverses
analytics_list_datasets	Schema	List datasets
analytics_describe_dataset	Schema	Field-level dataset description
analytics_infer_schema	Schema	INFER DATASET → JSON Schema
analytics_list_indexes	Schema	List Analytics secondary indexes
analytics_create_dataverse	Dataverse	CREATE DATAVERSE
analytics_drop_dataverse	Dataverse	DROP DATAVERSE
analytics_create_dataset	Dataverse	CREATE DATASET (shadow collection)
analytics_drop_dataset	Dataverse	DROP DATASET
analytics_alter_dataset	Dataverse	Modify dataset WHERE predicate
analytics_list_links	Links	List data source links
analytics_create_link	Links	Create CB/S3/Azure/GCS link
analytics_alter_link	Links	Update link configuration
analytics_drop_link	Links	Delete a link
analytics_connect_link	Links	Start ingestion (CONNECT LINK)
analytics_disconnect_link	Links	Pause ingestion (DISCONNECT LINK)
analytics_create_index	Indexes	CREATE Analytics secondary index
analytics_drop_index	Indexes	DROP Analytics secondary index
analytics_analyze_dataset	Indexes	Collect optimizer statistics
analytics_node_agg_stats	Cluster	Per-node resource stats
analytics_service_health	Cluster	Composite health summary
analytics_cluster_config	Cluster	Analytics service configuration
analytics_set_config_param	Cluster	Mutate config param (guarded)
analytics_restart_node	Cluster	Restart Analytics node(s) (guarded)

---

Development

# Install all workspace dependencies
npm install

# Build all packages
npm run build

# Run unit tests with coverage
npm run test:coverage

# Run integration tests (requires Couchbase)
docker-compose up -d couchbase
npm run test:integration -w packages/mcp-server

# Start dev server (hot reload)
npm run dev

# Generate API docs
npm run docs

Support Policy

I truly appreciate your interest in this project! This project is community-maintained. However, I actively monitor and maintain this repo and will try to resolve issues on a best-effort basis.

All inquiries should be through GitHub.

Bug reports: Open a GitHub issue
Feature requests: Open a GitHub issue with the "enhancement" label
Questions: Open a GitHub issue

Your collaboration helps me move forward together - thank you! Pull requests and contributions from the community are welcome and encouraged.

---

Architecture

See docs/architecture/ARCHITECTURE.md for the full component diagram, data flow description, and design decisions.