CouchDB MCP Server

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Integrations

  • Supports configuration through environment variables that can be stored in a .env file for CouchDB connection settings.

  • Provides specific configuration path information for Claude Desktop integration on macOS systems.

  • Serves as the runtime environment for the MCP server, with version 14 or higher required as a prerequisite.

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.

You must be authenticated.

A
security – no known vulnerabilities
F
license - not found
A
quality - confirmed to work

A TypeScript-based MCP server that enables AI assistants to interact with CouchDB databases through a simple interface, providing tools for creating, reading, and querying databases and documents.

  1. Features
    1. Tools
  2. Version Support
    1. Configuration
      1. Installation
        1. Installing via Smithery
        2. Prerequisites
        3. Debugging
      2. Error Handling