couchbase-mcp-server
Provides tools for querying Couchbase travel-sample data using SQL++, including connection summary, scopes/collections listing, query execution, document retrieval, and sample queries.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@couchbase-mcp-server List the top 5 hotels by highest rating."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.inventorydata.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?"
Related MCP server: Couchbase MCP Server for LLMs
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 |
| Shows the configured bucket, scope, host, and read/write mode without exposing secrets. |
| Lists scopes and collections in the configured Couchbase bucket. |
| Runs SQL++ in the configured bucket/scope query context. |
| Fetches a document from a named collection in the inventory scope. |
| 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-samplebucket loaded with theinventoryscope.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 .envThen 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-InstructRun the MCP Server
You can start the MCP server directly:
python -m couchbase_mcp_server.mcp_server --env-file .envThe 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.ipynbCLI:
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
inventoryscope.SQL++ queries should run in a scoped query context, so the
FROMclause 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
pytestFormat 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=falsefor 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
Available Tools
5 toolsget_connection_summaryA
Return non-secret Couchbase connection settings for this MCP server.
Inputs: no named parameters. Returns: object
get_document_by_idC
Fetch a single document by collection and document ID.
Inputs: document_id (required), collection_name (required), scope_name. Returns: object
get_sample_queriesA
Return SQL++ examples for the travel-sample inventory scope.
Inputs: no named parameters. Returns: object
get_scopes_and_collectionsA
List scopes and collections in the configured Couchbase bucket.
Inputs: no named parameters. Returns: object
run_sql_plus_plus_queryA
Run a SQL++ query in the configured bucket/scope query context.
The server is read-only by default. Set COUCHBASE_ALLOW_MUTATIONS=true to allow
write statements.
Inputs: query (required), max_rows, parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose: connection info, document retrieval, sample queries, schema listing, and query execution. No overlap between tools.
All tools follow a consistent 'verb_noun' pattern, using 'get_' for four tools and 'run_' for one, which is appropriate for the action. Naming is uniform and predictable.
With 5 tools, the set is well-scoped for a read-only Couchbase MCP server. Each tool serves a clear role without superfluous additions.
The tool set covers core read operations: schema exploration, document retrieval, and querying. A minor gap is the lack of a direct list-documents tool, but that can be achieved via queries.
Maintenance
Related MCP Connectors
Analytical memory for AI agents: a real Postgres queried in plain English over MCP. One command.
Query, explore, and manage your databases through natural conversation.
The BigQuery remote MCP server is a fully managed service that uses the Model Context Protocol to connect AI applications and LLMs to BigQuery data sources. It provides secure, standardized tools for AI agents to list datasets and tables, retrieve schemas, generate and execute SQL queries through natural language, and analyze data—enabling direct access to enterprise analytics data without requiring manual SQL coding.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA server that enables natural language interactions with Couchbase databases through the Model Context Protocol, allowing users to perform SQL++ queries on Couchbase Capella clusters using conversational commands.1MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables large language models to interact directly with Couchbase databases through natural language, supporting operations like querying buckets, performing CRUD operations, and executing N1QL queries.33 npm7MIT
- PythonApache 2.0
- FlicenseNot gradedqualityDmaintenanceEnables natural-language querying of structured data via Model Context Protocol, allowing AI agents to answer questions without SQL or API knowledge.-