CouchDB MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with CouchDB databases. This server enables Claude Code and other MCP clients to perform database operations, document management, and search queries on CouchDB instances.

Features

Database Operations

List Databases: View all databases on the CouchDB server
Create Database: Create new databases
Delete Database: Remove databases

Document Operations

Create Document: Insert new documents with optional custom IDs
Get Document: Retrieve documents by ID
Update Document: Modify existing documents
Delete Document: Remove documents
List Documents: View all documents in a database with optional full content

Search & Indexing

Search Documents: Query documents using CouchDB Mango queries with pagination support
Create Index: Create indexes for better query performance
List Indexes: View all indexes in a database

Requirements

Python 3.10 or higher
CouchDB server (local or remote)
Claude Code CLI

Installation

Clone or download this repository to your local machine.
Install dependencies using uv (recommended):

uv sync

Or using pip:

pip install -e .

CouchDB Setup

Make sure you have CouchDB installed and running. You can:

Install CouchDB locally:
- macOS: brew install couchdb
- Ubuntu/Debian: sudo apt-get install couchdb
- Or download from couchdb.apache.org

Use Docker:

docker run -d -p 5984:5984 --name couchdb \
  -e COUCHDB_USER=admin \
  -e COUCHDB_PASSWORD=password \
  couchdb:latest

Access CouchDB:
- Default URL: http://localhost:5984
- Web UI (Fauxton): http://localhost:5984/_utils

Adding to Claude Code

To use this MCP server with Claude Code, you need to add it to your Claude Code configuration file.

Configuration File Location

The Claude Code configuration file is located at:

macOS/Linux: ~/.config/claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuration Steps

Open or create the configuration file:

# macOS/Linux
mkdir -p ~/.config/claude
nano ~/.config/claude/claude_desktop_config.json

Add the CouchDB MCP server to the mcpServers section:

Using uv (recommended):

{
  "mcpServers": {
    "couchdb": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/couchdb_mcp",
        "python", "couchdb_mcp_server.py"
      ],
      "env": {
        "COUCHDB_URL": "http://localhost:5984"
      }
    }
  }
}

Using python directly (requires manual dependency install):

{
  "mcpServers": {
    "couchdb": {
      "command": "python",
      "args": [
        "/path/to/couchdb_mcp_server.py"
      ],
      "env": {
        "COUCHDB_URL": "http://localhost:5984"
      }
    }
  }
}

For authenticated CouchDB instances, include credentials in the URL:

{
  "mcpServers": {
    "couchdb": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/couchdb_mcp",
        "python", "couchdb_mcp_server.py"
      ],
      "env": {
        "COUCHDB_URL": "http://admin:password@localhost:5984"
      }
    }
  }
}

For remote CouchDB servers:

{
  "mcpServers": {
    "couchdb": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/couchdb_mcp",
        "python", "couchdb_mcp_server.py"
      ],
      "env": {
        "COUCHDB_URL": "https://username:[email protected]:5984"
      }
    }
  }
}

Save the configuration file and restart Claude Code.

Usage Examples

Once configured, you can use Claude Code to interact with your CouchDB instance. Here are some example requests:

Database Operations

Create a new database called "users"

List all databases

Delete the database named "test_db"

Document Operations

Create a document in the users database with data: {"name": "John Doe", "email": "[email protected]"}

Get the document with ID "user123" from the users database

Update document user123 in users database with new email address

List all documents in the users database

Search Operations

Search the users database for all documents where name equals "John Doe"

Search for documents in the products database where price is greater than 100

Tool Reference

couchdb_list_databases

Lists all databases on the CouchDB server.

Parameters: None

couchdb_create_database

Creates a new database.

Parameters:

name (string, required): Name of the database to create

couchdb_delete_database

Deletes a database.

Parameters:

name (string, required): Name of the database to delete

couchdb_create_document

Creates a new document in a database.

Parameters:

database (string, required): Name of the database
document (object, required): Document data as JSON object
doc_id (string, optional): Document ID (auto-generated if not provided)

couchdb_get_document

Retrieves a document from a database.

Parameters:

database (string, required): Name of the database
doc_id (string, required): Document ID

couchdb_update_document

Updates an existing document.

Parameters:

database (string, required): Name of the database
doc_id (string, required): Document ID
document (object, required): Updated document data (must include _rev)

couchdb_delete_document

Deletes a document from a database.

Parameters:

database (string, required): Name of the database
doc_id (string, required): Document ID
rev (string, required): Document revision (_rev)

couchdb_search_documents

Searches for documents using Mango queries.

Parameters:

database (string, required): Name of the database
query (object, required): Mango query selector (e.g., {"name": "John"})
limit (integer, optional): Maximum number of documents to return (default: 25)
skip (integer, optional): Number of documents to skip (default: 0)

couchdb_list_documents

Lists all documents in a database.

Parameters:

database (string, required): Name of the database
limit (integer, optional): Maximum number of documents to return
include_docs (boolean, optional): Include full document content (default: false)

couchdb_create_index

Creates an index to dramatically improve Mango query performance.

Parameters:

database (string, required): Name of the database
fields (array, required): Fields to index (e.g., ["type", "name"])
index_name (string, optional): Name for the index

Note: While indexes are optional, they are highly recommended. Without indexes, CouchDB scans all documents which can be very slow on large databases.

couchdb_list_indexes

Lists all indexes in a database.

Parameters:

database (string, required): Name of the database

About Indexes and Mango Queries

CouchDB's Mango query system (couchdb_search_documents) does not require indexes, but they are strongly recommended for performance.

According to the CouchDB documentation:

Without an index, CouchDB falls back to scanning all documents (_all_docs)
This works but "can be arbitrarily slow" on large databases
Creating indexes dramatically improves query performance

When to create indexes:

Your database has many documents (>1000)
Queries are slow
You frequently query the same fields

When you can skip indexes:

Small databases (<100 documents)
Infrequent queries
You don't mind slower response times

Example:

1. Try searching: "Search omnibot database where type equals 'name'"
2. If it works but is slow, create an index: "Create an index on the 'type' field in omnibot database"
3. Future queries will be much faster

Troubleshooting

Connection Issues

If you see connection errors:

Verify CouchDB is running: curl http://localhost:5984
Check the URL in your configuration
Verify credentials if using authentication
Check firewall settings for remote connections

Permission Errors

If you see permission errors:

Ensure the user has appropriate CouchDB permissions
Check that the database exists before performing document operations
Verify document revisions (_rev) when updating or deleting

Search Returns No Results

If you're searching for documents but getting no results:

Verify documents exist: Use couchdb_list_documents with include_docs: true to see actual document structure
Check field names match exactly: Field names are case-sensitive ("Type" ≠ "type")
Verify field values match: Values are also case-sensitive ("Name" ≠ "name")
Check the field exists: Queries only match documents where the field is present
Consider creating an index: While not required, indexes ensure queries work reliably and quickly

Tool Not Found

If Claude Code doesn't recognize the CouchDB tools:

Verify the configuration file path is correct
Ensure the --directory path (uv) or Python script path is absolute, not relative
Restart Claude Code after configuration changes
Check that dependencies are installed (uv sync or pip install -e .)

Mango Query Examples

Mango queries use MongoDB-style selectors:

Equality:

{"name": "John Doe"}

Comparison:

{"age": {"$gt": 18}}

Multiple conditions:

{"$and": [{"age": {"$gte": 18}}, {"status": "active"}]}

Pattern matching:

{"email": {"$regex": ".*@example\\.com$"}}

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.