CouchDB MCP Server

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_