README - Couchbase MCP Server (TypeScript/Bun Version) by zx8086

Couchbase MCP Server (TypeScript/Bun Version)

An MCP server implementation of Couchbase that allows LLMs to directly interact with Couchbase clusters.

Features

Tools

Database Operations

get_scopes_and_collections: List all scopes and collections in the specified bucket
get_schema_for_collection: Get the structure and schema for a specific collection
get_document_by_id: Retrieve a document by ID from a specified scope and collection
upsert_document_by_id: Create or update a document by ID in a specified scope and collection
delete_document_by_id: Remove a document by ID from a specified scope and collection
run_sql_plus_plus_query: Execute SQL++ queries on a specified scope

Query Analysis

get_detailed_indexes: Get comprehensive information about database indexes
get_detailed_prepared_statements: View detailed information about prepared statements
get_system_vitals: Monitor system health metrics
get_system_nodes: View information about cluster nodes
get_most_expensive_queries: Identify queries with highest resource consumption
suggest_query_optimizations: Get recommendations for query performance improvements
analyze_document_structure: Analyze and understand document structure patterns
get_document_type_examples: View example documents for different types
get_prepared_statements: List all prepared statements
get_indexes_to_drop: Identify unused or redundant indexes
get_completed_requests: View completed query requests
get_system_indexes: List all system indexes
get_primary_index_queries: Identify queries using primary indexes
get_largest_result_count_queries: Find queries returning the most results
get_largest_result_size_queries: Identify queries with largest result sizes
get_most_frequent_queries: View most commonly executed queries
get_longest_running_queries: Identify queries with longest execution times
get_fatal_requests: View failed query requests

Documentation Management

list_documentation: List available documentation for the MCP server tools and features
read_documentation: Read specific documentation entries
create_documentation: Create new documentation entries for tools and features
delete_documentation: Remove documentation entries
sync_documentation: Synchronize and update existing documentation

Playbook Management

list_playbooks: List available playbooks for database operations

Resources

Database Structure Resource: Access and manage database structure information
Schema Resource: Handle collection schemas and validation
Document Resource: Manage document operations and CRUD functionality
Query Resource: Handle SQL++ query operations and results
Query Analysis Resource: Monitor and optimize query performance
Documentation Resource: Manage tool and feature documentation
Playbook Resource: Manage and execute database operation playbooks

Security Features

READ_ONLY_QUERY_MODE: Default enabled setting to prevent SQL++ queries from modifying data
Secure document operations through ID-based access
Environment-based configuration for sensitive credentials

Prerequisites

Bun 1.0 or higher
A running Couchbase cluster. The easiest way to get started is to use Capella free tier, which is fully managed version of Couchbase server. You can follow instructions to import one of the sample datasets or import your own.
An MCP client such as Claude Desktop installed to connect the server to Claude. The instructions are provided for Claude Desktop and Cursor. Other MCP clients could be used as well.

Configuration

Clone the repository to your local machine.

git clone https://github.com/yourusername/mcp-server-couchbase-bun.git
cd mcp-server-couchbase-bun

Install dependencies:

bun install

Build the TypeScript project:

bun run build

Create a .env file based on the example:

cp .env.example .env
# Edit .env with your Couchbase credentials

Server Configuration for MCP Clients

This is the configuration for the MCP clients such as Claude Desktop, Cursor, Windsurf Editor.

{
  "mcpServers": {
    "couchbase-capella-mcp": {
      "command": "bun",
      "args": [
        "/path/to/your/mcp-server-couchbase/dist/index.js",
        "--transport",
        "stdio"
      ],
      "env": {
        "COUCHBASE_URL": "couchbases://your-cluster-url",
        "COUCHBASE_USERNAME": "your-username",
        "COUCHBASE_PASSWORD": "your-password",
        "COUCHBASE_BUCKET": "your-bucket",
        "COUCHBASE_SCOPE": "your-scope",
        "COUCHBASE_COLLECTION": "your-collection",
        "LOG_LEVEL": "debug",
        "DOCS_ENABLED": "true",
        "DOCS_BASE_DIR": "/path/to/your/mcp-server-couchbase/docs",
        "DOCS_FILE_EXT": ".md",
        "PWD": "/path/to/your/mcp-server-couchbase",
        "PATH": "/Users/your-username/.bun/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
      },
      "cwd": "/path/to/your/mcp-server-couchbase"
    }
  }
}

Note: Replace all /path/to/your/mcp-server-couchbase with the actual path to your cloned repository. Also, update the environment variables with your specific Couchbase cluster details.

The server can be configured using environment variables. The following variables are supported:

Couchbase Connection Settings

COUCHBASE_URL: The connection string to the Couchbase cluster
COUCHBASE_USERNAME: The username with access to the bucket to use to connect
COUCHBASE_PASSWORD: The password for the username to connect
COUCHBASE_BUCKET: The name of the bucket that the server will access
COUCHBASE_SCOPE: The scope to use within the bucket
COUCHBASE_COLLECTION: The collection to use within the scope
CN_ROOT: The root directory for Couchbase configuration (default: '/usr/src')

MCP Server Settings

MCP_SERVER_NAME: The name of the MCP server instance
MCP_TRANSPORT: The transport mode to use (stdio or sse)
FASTMCP_PORT: The port number for SSE transport mode (default: 8080)
READ_ONLY_QUERY_MODE: Setting to configure whether SQL++ queries that allow data to be modified are allowed (default: true)
LOG_LEVEL: The logging level (e.g., "debug", "info", "warn", "error")

Documentation Settings

DOCS_ENABLED: Enable/disable documentation features
DOCS_BASE_DIR: Base directory for documentation files
DOCS_FILE_EXT: File extension for documentation files

Playbook Settings

PLAYBOOKS_ENABLED: Enable/disable playbook features
PLAYBOOKS_BASE_DIR: Base directory for playbook files
PLAYBOOKS_FILE_EXT: File extension for playbook files

System Settings

PWD: The working directory for the MCP server

Running the Server

You can run the server directly with:

# Development mode (TypeScript directly)
bun run dev

# Production mode (compiled JavaScript)
bun run start

For SSE transport mode:

# Development mode (TypeScript directly)
bun run dev:sse

# Production mode (compiled JavaScript)
bun run start:sse

Client Setup Instructions

Setup instructions for Claude Desktop, Cursor, and Windsurf Editor remain the same as the original Python version, just adjust the command to use bun instead of uv.

SSE Server Mode

There is an option to run the MCP server in Server-Sent Events (SSE) transport mode.

Usage

By default, the MCP server will run on port 8080 but this can be configured using the FASTMCP_PORT environment variable.

bun run dist/mcp_server.js --connection-string='<couchbase_connection_string>' --username='<database_username>' --password='<database_password>' --bucket-name='<couchbase_bucket_to_use>' --read-only-query-mode=true --transport=sse

The server will be available on http://localhost:8080/sse. This can be used in MCP clients supporting SSE transport mode.

Risks Associated with LLMs

The use of large language models and similar technology involves risks, including the potential for inaccurate or harmful outputs.
Couchbase does not review or evaluate the quality or accuracy of such outputs, and such outputs may not reflect Couchbase's views.
You are solely responsible for determining whether to use large language models and related technology, and for complying with any license terms, terms of use, and your organization's policies governing your use of the same.

TypeScript Implementation Notes

This implementation offers several advantages over the original Python version:

Type Safety: Strong typing for all functions, parameters, and return values
Developer Experience: Better IDE support with autocompletion and inline documentation
Performance: Bun runtime provides excellent performance for JavaScript/TypeScript applications

Troubleshooting Tips

Ensure the path to your MCP server repository is correct in the configuration.
Verify that your Couchbase connection string, database username, password and bucket name are correct.
If using Couchbase Capella, ensure that the cluster is accessible from the machine where the MCP server is running.
Check that the database user has proper permissions to access the specified bucket.
Confirm that Bun is properly installed and accessible.
Check the logs for any errors or warnings that may indicate issues with the MCP server.

Support Policy

We truly appreciate your interest in this project! This project is community-maintained, which means it's not officially supported by a support team.

If you need help, have found a bug, or want to contribute improvements, the best place to do that is right here — by opening a GitHub issue. Our support portal is unable to assist with requests related to this project, so we kindly ask that all inquiries stay within GitHub.

Your collaboration helps us all move forward together — thank you!