CouchDB MCP Server
About
# couchdb-mcp-server [](https://smithery.ai/server/@robertoamoreno/couchdb-mcp-server) A Model Context Protocol server for interacting with CouchDB This is a TypeScript-based MCP server that provides tools for managing CouchDB databases and…
Explore
- Create, list, and delete CouchDB databases
- Create, read, and update documents
- Automatically detects create vs update operations
- Create, delete, and list Mango indexes (CouchDB 3.x+)
- Query documents with Mango query syntax
- Robust error handling for common scenarios
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
CouchDB MCP ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
The server requires a CouchDB connection URL and version. These can be provided through environment variables:
COUCHDB_URL=http://username:password@localhost:5984
COUCHDB_VERSION=1.7.2
You can create a .env file in the project root with this configuration. If not provided, it defaults to http://localhost:5984.
To install couchdb-mcp-server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @robertoamoreno/couchdb-mcp-server --client claude
To use with Claude Desktop, add the server config:
On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"couchdb-mcp-server": {
"command": "/path/to/couchdb-mcp-server/build/index.js",
"env": {
"COUCHDB_URL": "http://username:password@localhost:5984"
}
}
}
}
```
createDatabase
Create a new CouchDB database
listDatabases
List all CouchDB databases
deleteDatabase
Delete a CouchDB database
createDocument
Create a new document or update an existing document in a database
dbName
Database name
docId
Document ID
data
Document data (JSON object)
getDocument
Get a document from a database
createMangoIndex
Create a new Mango index
indexName
Name of the index
fields
Array of field names to index
deleteMangoIndex
Delete a Mango index
designDoc
Design document name
listMangoIndexes
List all Mango indexes in a database
findDocuments
Query documents using Mango query
query
Mango query object
- createDatabase - Create a new CouchDB database
- Takes dbName as a required parameter
- Creates the database if it doesn't exist
- listDatabases - List all CouchDB databases
- Returns an array of database names
- deleteDatabase - Delete a CouchDB database
- Takes dbName as a required parameter
- Removes the specified database and all its documents
- createDocument - Create a new document or update an existing document in a database
- Required parameters:
- dbName: Database name
- docId: Document ID
- data: Document data (JSON object)
- For updates, include _rev field with the current document revision
- Returns:
- For new documents: document ID and new revision
- For updates: document ID and updated revision
- Automatically detects if operation is create or update based on presence of _rev field
- getDocument - Get a document from a database
- Required parameters:
- dbName: Database name
- docId: Document ID
- Returns the document content
- createMangoIndex - Create a new Mango index
- Required parameters:
- dbName: Database name
- indexName: Name of the index
- fields: Array of field names to index
- Creates a new index for efficient querying
- deleteMangoIndex - Delete a Mango index
- Required parameters:
- dbName: Database name
- designDoc: Design document name
- indexName: Name of the index
- Removes an existing Mango index
- listMangoIndexes - List all Mango indexes in a database
- Required parameters:
- dbName: Database name
- Returns information about all indexes in the database
- findDocuments - Query documents using Mango query
- Required parameters:
- dbName: Database name
- query: Mango query object
- Performs a query using CouchDB's Mango query syntax
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"couchdb mcp server": {
"couchdb-mcp-server": {
"command": "npx",
"args": [
"-y",
"@smithery/cli",
"install",
"@robertoamoreno/couchdb-mcp-server",
"--client",
"claude"
]
}
}
}
}McpServers
{
"couchdb-mcp-server": {
"command": "npx",
"args": [
"-y",
"@smithery/cli",
"install",
"@robertoamoreno/couchdb-mcp-server",
"--client",
"claude"
]
}
}A Model Context Protocol server for interacting with CouchDB
This is a TypeScript-based MCP server that provides tools for managing CouchDB databases and documents. It enables AI assistants to interact with CouchDB through a simple interface.
Features
Tools
Base Tools (All CouchDB Versions)
-createDatabase - Create a new CouchDB database
- Takes dbName as a required parameter
- Creates the database if it doesn't exist
- listDatabases - List all CouchDB databases
- Returns an array of database names
- deleteDatabase - Delete a CouchDB database
- Takes dbName as a required parameter
- Removes the specified database and all its documents
- createDocument - Create a new document or update an existing document in a database
- Required parameters:
- dbName: Database name
- docId: Document ID
- data: Document data (JSON object)
- For updates, include _rev field with the current document revision
- Returns:
- For new documents: document ID and new revision
- For updates: document ID and updated revision
- Automatically detects if operation is create or update based on presence of _rev field
- getDocument - Get a document from a database
- Required parameters:
- dbName: Database name
- docId: Document ID
- Returns the document content
Mango Query Tools (CouchDB 3.x+ Only)
-createMangoIndex - Create a new Mango index
- Required parameters:
- dbName: Database name
- indexName: Name of the index
- fields: Array of field names to index
- Creates a new index for efficient querying
- deleteMangoIndex - Delete a Mango index
- Required parameters:
- dbName: Database name
- designDoc: Design document name
- indexName: Name of the index
- Removes an existing Mango index
- listMangoIndexes - List all Mango indexes in a database
- Required parameters:
- dbName: Database name
- Returns information about all indexes in the database
- findDocuments - Query documents using Mango query
- Required parameters:
- dbName: Database name
- query: Mango query object
- Performs a query using CouchDB's Mango query syntax
Version Support
The server automatically detects the CouchDB version and enables features accordingly:
- All versions: Basic database and document operations
- CouchDB 3.x+: Mango query support (indexes and queries)
Configuration
The server requires a CouchDB connection URL and version. These can be provided through environment variables:
COUCHDB_URL=http://username:password@localhost:5984
COUCHDB_VERSION=1.7.2
You can create a .env file in the project root with this configuration. If not provided, it defaults to http://localhost:5984.
Development
Install dependencies:
npm install
Build the server:
npm run build
For development with auto-rebuild:
npm run watch
Installation
Installing via Smithery
To install couchdb-mcp-server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @robertoamoreno/couchdb-mcp-server --client claude
To use with Claude Desktop, add the server config:
On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"couchdb-mcp-server": {
"command": "/path/to/couchdb-mcp-server/build/index.js",
"env": {
"COUCHDB_URL": "http://username:password@localhost:5984"
}
}
}
}
Prerequisites
- Node.js 14 or higher
- Running CouchDB instance
- Proper CouchDB credentials if authentication is enabled
Debugging
Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:
npm run inspector
```
The Inspector will provide a URL to access debugging tools in your browser.
Error Handling
The server includes robust error handling for common scenarios:
- Invalid database names or document IDs
- Database already exists/doesn't exist
- Connection issues
- Authentication failures
- Invalid document data
All errors are properly formatted and returned through the MCP protocol with appropriate error codes and messages.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
