Couchdb MCP Server

🚀 CouchDB-MCP-Server

A Model Context Protocol (MCP) 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.

🚀 Quick Start

The CouchDB-MCP-Server allows you to interact with CouchDB databases and documents easily. You can manage databases, create and update documents, and perform Mango queries (for CouchDB 3.x+).

✨ Features

Tools

Basic Tools (All CouchDB Versions)

• createDatabase - Create a new CouchDB database

  • Required parameter: dbName
  • Creates the database if it does not exist

• listDatabases - List all CouchDB databases

  • Returns an array containing the names of the databases

• deleteDatabase - Delete a CouchDB database

  • Required parameter: dbName
  • Removes the specified database and all its documents

• createDocument - Create a new document or update an existing one

  • Required parameters:

    • dbName: Name of the database
    • docId: ID of the document
    • data: Document data (JSON object)
      • When updating, include the _rev field with the current document version

  • Returns:

    • For a new document: Document ID and new revision
    • For an update: Document ID and updated revision
    • Automatically detects whether to create or update based on the presence of the _rev field

• getDocument - Get a document from the database

  • Required parameters:
    • dbName: Name of the database
    • docId: ID of the document
  • Returns the document content

Mango Query Tools (CouchDB 3.x+ Only)

• createMangoIndex - Create a new Mango index

  • Required parameters:
    • dbName: Name of the database
    • indexName: Name of the index
    • fields: Array of fields to index
  • Creates a new Mango index for efficient queries

• deleteMangoIndex - Delete a Mango index

  • Required parameters:
    • dbName: Name of the database
    • designDoc: Name of the design document
    • indexName: Name of the index
  • Removes an existing Mango index

• listMangoIndexes - List all Mango indexes in the database

  • Required parameter:
    • dbName: Name of the database
  • Returns information about all indexes

• findDocuments - Query documents using Mango

  • Required parameters:
    • dbName: Name of the database
    • 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 (indexing and querying)

🔧 Configuration

The server requires the CouchDB connection URL and version. These can be provided via environment variables:

COUCHDB_URL=http://username:password@localhost:5984
COUCHDB_VERSION=1.7.2

You can create a .env file in the project root directory containing this configuration. If not provided, the default is http://localhost:5984.

💻 Development

Install dependencies:

npm install

Build the server:

npm run build

Development with automatic rebuild:

npm run watch

📦 Installation

Install via Smithery

To automatically install couchdb-mcp-server for Claude Desktop via Smithery:

npx -y @smithery/cli install @robertoamoreno/couchdb-mcp-server --client claude

To use it with Claude Desktop, add the server configuration:

On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "servers": {
    "couchdb-mcp-server": {
      "url": "http://localhost:4000",
      "username": "admin",
      "password": "password"
    }
  }
}

🔧 Error Handling

The server includes robust error handling for common scenarios:

• Invalid database name or document ID
• Database already exists/does not exist
• Connection issues
• Authentication failure
• Invalid document data

All errors are returned via the MCP protocol in an appropriate status code and message format.