de en es ja ko ru zh

Couchbase-Analytics-MCP

Name: Couchbase-Analytics-MCP
Author: celticht32

by celticht32

Overview Schema Related Servers Score Discussions

TypeScript

Remote

Couchbase-Analytics-MCP

Couchbase Enterprise Analytics 서비스를 위한 프로덕션급 MCP(Model Context Protocol) 서버입니다. 전체 Analytics API를 25개의 강력한 유형의 MCP 도구로 노출하며, 내장 GUI 콘솔, 구조화된 로깅, Prometheus 메트릭, OpenTelemetry 추적 및 포괄적인 테스트 커버리지를 제공합니다.

중요: 이 서버는 Couchbase Query(N1QL) 서비스가 아닌 Analytics 서비스(Apache AsterixDB 엔진, SQL++, 포트 8095)를 대상으로 합니다. 모든 도구는 cluster.analyticsQuery() 및 /analytics/* REST 엔드포인트만 호출합니다.

기능 매트릭스

기능	상태
전체 Analytics API를 포함하는 25개의 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 차트	✅
GitHub Actions CI/CD	✅
아키텍처 문서 + ADR	✅
운영 런북	✅

빠른 시작

사전 요구 사항

Node.js ≥ 20
Docker + Docker Compose
Analytics 서비스가 활성화된 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`	Analytics 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 복제 지연
`analytics_list_dataverses`	스키마	모든 데이터버스 나열
`analytics_list_datasets`	스키마	데이터셋 나열
`analytics_describe_dataset`	스키마	필드 수준 데이터셋 설명
`analytics_infer_schema`	스키마	INFER DATASET → JSON 스키마
`analytics_list_indexes`	스키마	Analytics 보조 인덱스 나열
`analytics_create_dataverse`	데이터버스	CREATE DATAVERSE
`analytics_drop_dataverse`	데이터버스	DROP DATAVERSE
`analytics_create_dataset`	데이터버스	CREATE DATASET (섀도우 컬렉션)
`analytics_drop_dataset`	데이터버스	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 보조 인덱스 생성
`analytics_drop_index`	인덱스	Analytics 보조 인덱스 삭제
`analytics_analyze_dataset`	인덱스	옵티마이저 통계 수집
`analytics_node_agg_stats`	클러스터	노드별 리소스 통계
`analytics_service_health`	클러스터	복합 상태 요약
`analytics_cluster_config`	클러스터	Analytics 서비스 구성
`analytics_set_config_param`	클러스터	구성 매개변수 변경 (보호됨)
`analytics_restart_node`	클러스터	Analytics 노드 재시작 (보호됨)

개발

# 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

여러분의 협력은 제가 함께 나아가는 데 큰 도움이 됩니다. 감사합니다! 커뮤니티의 풀 리퀘스트와 기여를 환영하며 적극 권장합니다.

아키텍처

전체 구성 요소 다이어그램, 데이터 흐름 설명 및 설계 결정 사항은 docs/architecture/ARCHITECTURE.md를 참조하세요.

This server cannot be installed

license - permissive license

Not graded

quality - not tested

Not graded

maintenance - not tested

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Related Servers

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

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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