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

1. Clone or download this repository to your local machine.

2. 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:

1. Install CouchDB locally:

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

2. Use Docker:

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

3. 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

1. Open or create the configuration file:

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

2. 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"
      }
    }
  }
}

3. 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"
      }
    }
  }
}

4. 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:password@your-server.com:5984"
      }
    }
  }
}

5. 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": "john@example.com"}

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:

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

Permission Errors

If you see permission errors:

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

Search Returns No Results

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

1. Verify documents exist: Use couchdb_list_documents with include_docs: true to see actual document structure
2. Check field names match exactly: Field names are case-sensitive ("Type" ≠ "type")
3. Verify field values match: Values are also case-sensitive ("Name" ≠ "name")
4. Check the field exists: Queries only match documents where the field is present
5. 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:

1. Verify the configuration file path is correct
2. Ensure the --directory path (uv) or Python script path is absolute, not relative
3. Restart Claude Code after configuration changes
4. 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.