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

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

Tool reference

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

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.