Couchbase

🚀 Couchbase MCP Server

The Model Context Protocol (MCP) is a protocol (https://modelcontextprotocol.io/introduction) designed to handle interactions between Large Language Models (LLMs) and external systems. This repository implements a Couchbase MCP Server using the Couchbase Node.js SDK, enabling MCP clients (such as Claude Desktop) to perform natural language queries on Couchbase Capella clusters.

With this server, you can use commands like:

• Show me the results of SELECT * FROM my_bucket LIMIT 10
• Execute this query: SELECT name, age FROM users WHERE active = true
• Get me the latest 5 documents from my_bucket
• Summarize the latest 5 orders from the orders bucket for me

🚀 Quick Start

The following figure demonstrates how the MCP server works when interacting with the Claude Desktop client. The user makes a general request in plain English, and the MCP server converts it into a SQL++ query and executes it on the Couchbase Capella cluster. The results are then returned to the user in a readable format.

📦 Installation

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 in the root directory and add your Couchbase connection string, username, and password:

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

Refer to the .env.sample file for the required environment variables.

3. Build the project:

npm run build

4. Run the server using Stdio transport:

npx couchbase-mcp-server

⚠️ Important Note

The MCP server uses StdioServerTransport, so it communicates via standard input/output. Make sure your MCP client (e.g., Claude Desktop) is configured to connect to the local MCP server. Follow the Claude Desktop documentation to configure your MCP client to connect to the local server.

✨ Features

Couchbase Query Tool

• Tool Name: query-couchbase
• Description: Execute SQL++ query statements on your Couchbase Capella cluster.
• Usage: When invoked, the server will execute the provided SQL++ query using the Couchbase Node.js SDK and return the results.

📚 Documentation

Local Development

To work locally:

1. Install dependencies:

npm install
npm run build

2. Test the server with an MCP client:

Start your MCP client (e.g., Claude Desktop), configure it to connect, and call the tool with sample queries.

3. Debugging

All log messages are sent to stderr to ensure that stdout only contains MCP protocol JSON. Check the logs for detailed connection and error messages.

🤝 Contribution

Contributions are welcome! Feel free to submit pull requests or open issues to share your suggestions. For any changes, please follow the project's code style.

📄 License

This project is released under the MIT License. For more details, see the LICENSE file.