couchbase

This MCP server enables natural language interaction with a Couchbase Capella cluster. It exposes a tool called query-couchbase that translates natural language queries into SQL++ (N1QL) statements and executes them against your Couchbase cluster using the Couchbase Node.js SDK. You can ask it to run SELECT queries, retrieve recent documents from a bucket, or summarize data, for example: 'Show me the results of SELECT * FROM my_bucket LIMIT 10' or 'Get the latest 5 documents from the orders bucket'. The server handles translating the request, executing the query, and returning structured results back through the MCP protocol. When using Claude Desktop or another MCP client, ensure the client is configured to communicate with the local Stdio transport exposed by this server. The Included tool, query-couchbase, is designed to interface with your Capella cluster securely using the environment-provided credentials.

Prerequisites:

• Node.js and npm installed on your machine
• Access to a Couchbase Capella cluster with a connection string, username, and password

Steps:

1. Clone the repository and install dependencies

git clone git@github.com:hummusonrails/couchbase-mcp-server.git
cd couchbase-mcp-server
npm install

2. Create a .env file (or rely on the provided env vars in MCP config) with Couchbase connection details:

COUCHBASE_CONNECTION_STRING=couchbases://your-cluster.cloud.couchbase.com
COUCHBASE_USERNAME=your_username
COUCHBASE_PASSWORD=your_password

3. Build the project (if a build script is defined):

npm run build

4. Run the MCP server via npx (Stdio transport):

npx couchbase-mcp-server

5. Verify connectivity with your MCP client (e.g., Claude Desktop) configured to connect to the local Stdio server as described in the Claude Desktop docs.

Environment variables control access to your Couchbase cluster. Ensure that COUCHBASE_CONNECTION_STRING, COUCHBASE_USERNAME, and COUCHBASE_PASSWORD are kept secret. All MCP logs are written to stderr to avoid polluting stdout with protocol messages. If you encounter connection issues, verify network access to the Couchbase Capella cluster and confirm the credentials. The server exposes a single tool, query-couchbase, which runs the provided SQL++ statements against the cluster and returns results in a readable format. If you plan to deploy in a production environment, consider wrapping the process in a proper supervisor and securing credentials via a vault or environment management system.