Couchbase MCP Server

A production-shaped demo that connects a natural-language AI agent to Couchbase through the Model Context Protocol (MCP). It uses the OpenAI Agents SDK as the agent runtime, a stdio MCP server as the tool bridge, Couchbase travel-sample as the data source, and a Nebius-hosted OpenAI-compatible model as the LLM backend.

Live project site: https://tirth1263.github.io/couchbase-mcp-server/

Why This Project Exists

LLMs are good at understanding intent, but they need trustworthy tools to answer questions grounded in private or operational data. MCP gives those tools a standard shape. This repository demonstrates that pattern end to end:

• A user asks a plain-English travel question.
• The OpenAI Agents SDK agent decides whether it needs database context.
• The agent calls a Couchbase MCP tool over stdio.
• The MCP server executes scoped SQL++ against the travel-sample.inventory data.
• The agent turns the database result into a clear recommendation or answer.

Example questions:

• "List out the top 5 hotels by the highest aggregate rating."
• "Recommend me a flight and hotel from New York to San Francisco."
• "Which airports are near San Francisco and what routes connect to them?"

Architecture

flowchart LR
    U["User question"] --> N["main.ipynb / CLI demo"]
    N --> A["OpenAI Agents SDK agent"]
    A --> M["MCPServerStdio client"]
    M <--> S["Couchbase MCP server"]
    S --> C["Couchbase travel-sample bucket"]
    A --> L["Nebius OpenAI-compatible LLM"]
    C --> S --> M --> A --> R["Natural-language answer"]

What Is Included

• src/couchbase_mcp_server/mcp_server.py - the stdio MCP server.
• src/couchbase_mcp_server/couchbase_client.py - Couchbase SDK wrapper and JSON serialization.
• src/couchbase_mcp_server/demo_agent.py - command-line OpenAI Agents SDK demo.
• main.ipynb - Jupyter notebook version of the demo.
• .env.example - environment variables for Couchbase and Nebius.
• docs/ - static GitHub Pages website.
• tests/ - focused safety tests for SQL++ mutation detection.

MCP Tools Exposed

Tool	Purpose
get_connection_summary	Shows the configured bucket, scope, host, and read/write mode without exposing secrets.
get_scopes_and_collections	Lists scopes and collections in the configured Couchbase bucket.
run_sql_plus_plus_query	Runs SQL++ in the configured bucket/scope query context.
get_document_by_id	Fetches a document from a named collection in the inventory scope.
get_sample_queries	Returns useful SQL++ examples for the travel-sample inventory data.

By default, run_sql_plus_plus_query blocks mutations such as INSERT, UPDATE, DELETE, MERGE, CREATE, DROP, and ALTER. Set COUCHBASE_ALLOW_MUTATIONS=true only when you intentionally want write-capable tools.

Prerequisites

• Python 3.11 or newer. Python 3.12 is recommended.
• Jupyter Notebook or JupyterLab for main.ipynb.
• A running Couchbase Server or Couchbase Capella instance.
• The travel-sample bucket loaded with the inventory scope.
• A Nebius API key for an OpenAI-compatible chat model endpoint.

Quick Start

Clone and install:

git clone https://github.com/tirth1263/couchbase-mcp-server.git
cd couchbase-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -e ".[notebook]"

On Windows PowerShell:

git clone https://github.com/tirth1263/couchbase-mcp-server.git
cd couchbase-mcp-server
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[notebook]"

Create your environment file:

cp .env.example .env

Then edit .env:

COUCHBASE_HOST=couchbases://your-capella-endpoint
COUCHBASE_BUCKET_NAME=travel-sample
COUCHBASE_SCOPE_NAME=inventory
COUCHBASE_USERNAME=your_couchbase_username
COUCHBASE_PASSWORD=your_couchbase_password
NEBIUS_API_KEY=your_nebius_api_key
NEBIUS_BASE_URL=https://api.studio.nebius.ai/v1/
NEBIUS_MODEL=meta-llama/Meta-Llama-3.1-8B-Instruct

Run the MCP Server

You can start the MCP server directly:

python -m couchbase_mcp_server.mcp_server --env-file .env

The server uses stdio, so it is usually launched by an MCP client rather than run interactively. Logs are written to stderr so stdout stays reserved for MCP messages.

Run the Agent Demo

Notebook:

jupyter lab main.ipynb

CLI:

couchbase-agent-demo "List the top 5 hotels by aggregate rating."

Or:

python -m couchbase_mcp_server.demo_agent \
  --env-file .env \
  "Recommend a flight and hotel from New York to San Francisco."

Agent Instructions

The demo agent is intentionally explicit about Couchbase structure:

• A Couchbase cluster contains buckets.
• A bucket contains scopes.
• A scope contains collections.
• Collections contain JSON documents.
• The target demo data lives in the inventory scope.
• SQL++ queries should run in a scoped query context, so the FROM clause can use collection names like `hotel` rather than fully qualified paths.
• All identifiers should be wrapped in backticks.

That last point matters because SQL++ collection and field names can collide with keywords or include characters that need quoting.

Website

The public website is served from docs/ using GitHub Pages:

https://tirth1263.github.io/couchbase-mcp-server/

The site is a static deployment artifact, so it can also be hosted on Netlify, Vercel, Cloudflare Pages, or any static web server without a build step.

Development

Run validation:

python scripts/validate_project.py
python -m compileall src
pytest

Format and lint if you install the dev extras:

pip install -e ".[dev,notebook]"
ruff check .
ruff format .

Security Notes

• Do not commit .env; it is intentionally ignored.
• Keep COUCHBASE_ALLOW_MUTATIONS=false for demos, workshops, and public examples.
• Use a least-privilege Couchbase user with access only to the demo bucket/scope.
• Prefer read-only database credentials unless you are intentionally demonstrating write tools.
• Treat LLM-generated SQL++ as untrusted input and keep server-side guardrails in place.

References

• OpenAI Agents SDK: https://openai.github.io/openai-agents-python/
• Agents SDK MCP integration: https://openai.github.io/openai-agents-python/mcp/
• Model Context Protocol: https://modelcontextprotocol.io/
• Couchbase Python SDK: https://docs.couchbase.com/python-sdk/current/hello-world/start-using-sdk.html
• Couchbase travel-sample: https://docs.couchbase.com/server/current/getting-started/do-a-quick-install.html#install-sample-buckets