Skip to main content
Glama
deenesjakoruzh
celticht32

Couchbase-Analytics-MCP

by celticht32
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

Couchbase-Analytics-MCP

一个用于 Couchbase 企业级分析 (Couchbase Enterprise Analytics) 服务的生产级 模型上下文协议 (MCP) 服务器。它将完整的分析 API 暴露为 25 个强类型的 MCP 工具，并内置了 GUI 控制台、结构化日志记录、Prometheus 指标、OpenTelemetry 追踪以及全面的测试覆盖。

重要提示： 此服务器针对的是分析服务（Apache AsterixDB 引擎，SQL++，端口 8095）—— 而不是 Couchbase 查询 (N1QL) 服务。所有工具仅调用 cluster.analyticsQuery() 和 /analytics/* REST 端点。

功能矩阵

功能

状态

25 个涵盖完整分析 API 的 MCP 工具

✅

stdio 传输 (Claude Desktop)

✅

SSE/HTTP 传输 (远程代理)

✅

连接池 (最小/最大/空闲回收)

✅

SSE 端点上的 JWT + API 密钥认证

✅

结构化 JSON 日志 (Pino)

✅

每日日志轮转 (pino-roll)

✅

可选的 Loki 推送传输

✅

Prometheus /metrics 端点

✅

OpenTelemetry 追踪 → Jaeger

✅

/health/live + /health/ready 探针

✅

/console 处的 React GUI 控制台

✅

Monaco SQL++ 编辑器

✅

模式浏览器 (数据空间 → 数据集树)

✅

实时工具调用检查器

✅

单元测试 (≥90% 覆盖率)

✅

集成测试 (真实的 Couchbase)

✅

E2E 测试 (Supertest SSE 传输)

✅

Docker 多阶段镜像

✅

Docker Compose (CB + Prometheus + Grafana + Jaeger)

✅

Helm chart

✅

GitHub Actions CI/CD

✅

架构文档 + ADR

✅

操作手册

✅

快速入门

先决条件

  • Node.js ≥ 20

  • Docker + Docker Compose

  • 启用了分析服务的 Couchbase Server Enterprise ≥ 7.2

本地开发 (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

针对现有的 Couchbase 集群运行

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 集成

添加到 ~/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"
      }
    }
  }
}

环境变量

变量

默认值

描述

CB_CONNECTION_STRING

(必填)

couchbase://host 或用于 TLS 的 couchbases://host

CB_USERNAME

(必填)

Couchbase RBAC 用户名

CB_PASSWORD

(必填)

Couchbase RBAC 密码

CB_ANALYTICS_PORT

8095

分析 REST 端口 (TLS 为 18095)

CB_ANALYTICS_TLS

false

为 REST 调用启用 TLS

TRANSPORT

stdio

stdio 或 sse

PORT

3000

HTTP 服务器端口 (SSE + 健康检查 + GUI)

POOL_MIN

2

最小连接池连接数

POOL_MAX

10

最大连接池连接数

POOL_IDLE_TIMEOUT_MS

30000

空闲连接回收阈值

QUERY_DEFAULT_TIMEOUT_MS

60000

默认查询超时时间

LOG_LEVEL

info

`trace

debug

info

warn

error

fatal`

LOG_FORMAT

json

`json

pretty`

LOG_FILE_ENABLED

false

启用文件传输

LOG_FILE_PATH

/var/log/cba-mcp/server.log

日志文件路径

LOKI_HOST

(可选)

Loki 推送端点

METRICS_ENABLED

true

暴露 /metrics

OTEL_ENABLED

false

启用 OpenTelemetry 追踪

JAEGER_ENDPOINT

http://localhost:14268/api/traces

Jaeger HTTP 收集器

JWT_SECRET

(可选)

用于 SSE 认证的 JWT 签名密钥

API_KEY

(可选)

用于 SSE 认证的静态 API 密钥

GUI_ENABLED

true

在 /console 提供 GUI 服务

工具参考

请参阅 docs/api/TOOLS.md 获取完整的输入/输出模式。

工具

组

描述

analytics_execute

查询

执行 SQL++ 语句

analytics_explain

查询

返回查询执行计划

analytics_cancel

查询

取消正在运行的查询

analytics_query_status

查询

检查异步查询状态

analytics_pending_mutations

查询

KV→分析复制延迟

analytics_list_dataverses

模式

列出所有数据空间 (dataverses)

analytics_list_datasets

模式

列出数据集

analytics_describe_dataset

模式

字段级数据集描述

analytics_infer_schema

模式

INFER DATASET → JSON 模式

analytics_list_indexes

模式

列出分析二级索引

analytics_create_dataverse

数据空间

创建数据空间

analytics_drop_dataverse

数据空间

删除数据空间

analytics_create_dataset

数据空间

创建数据集 (影子集合)

analytics_drop_dataset

数据空间

删除数据集

analytics_alter_dataset

数据空间

修改数据集 WHERE 谓词

analytics_list_links

链接

列出数据源链接

analytics_create_link

链接

创建 CB/S3/Azure/GCS 链接

analytics_alter_link

链接

更新链接配置

analytics_drop_link

链接

删除链接

analytics_connect_link

链接

开始摄取 (CONNECT LINK)

analytics_disconnect_link

链接

暂停摄取 (DISCONNECT LINK)

analytics_create_index

索引

创建分析二级索引

analytics_drop_index

索引

删除分析二级索引

analytics_analyze_dataset

索引

收集优化器统计信息

analytics_node_agg_stats

集群

每个节点的资源统计信息

analytics_service_health

集群

综合健康摘要

analytics_cluster_config

集群

分析服务配置

analytics_set_config_param

集群

修改配置参数 (受保护)

analytics_restart_node

集群

重启分析节点 (受保护)

开发

# 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

支持政策

非常感谢您对本项目的关注！本项目由社区维护。但我会积极监控和维护此仓库，并尽力解决问题。

所有咨询应通过 GitHub 进行。

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

您的协作有助于我们共同进步——谢谢！欢迎并鼓励社区提交 Pull Request 和贡献。

架构

请参阅 docs/architecture/ARCHITECTURE.md 获取完整的组件图、数据流描述和设计决策。

This server cannot be installed

A
license - permissive license
Not graded
quality - not tested
Not graded
maintenance - not tested

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

  • mcp

    MCP server for managing Prisma Postgres.

  • mcp

    MCP server providing access to the Scorecard API to evaluate and optimize LLM systems.

  • InsForge

    MCP server for InsForge BaaS — database, storage, edge functions, and deployments

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/celticht32/MCP-Couchbase-Analytics'

If you have feedback or need assistance with the MCP directory API, please join our Discord server