What is Couchdb Mcp Server

couchdb-mcp-server is a Model Context Protocol server designed for interacting with CouchDB. It is built using TypeScript and provides tools for managing CouchDB databases and documents, allowing AI assistants to communicate with CouchDB through a simple interface.

Use cases

Use cases include building AI applications that need to store and retrieve data from CouchDB, managing document lifecycles, and performing complex queries using Mango syntax for data analysis.

How to use

To use couchdb-mcp-server, install it via Smithery or manually set it up in your environment. Configure the CouchDB connection URL and version in a .env file. You can then utilize various tools to create, list, delete databases, and manage documents.

Key features

Key features include basic database operations (create, list, delete databases), document management (create, update, get documents), and Mango query support for CouchDB 3.x and above (creating and deleting indexes, querying documents).

Where to use

couchdb-mcp-server can be used in applications that require database management and document storage, particularly in AI-driven environments where CouchDB serves as the backend database.

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 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:
```bash
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.