couchdb

This MCP server provides a set of tools to manage CouchDB databases and documents through the Model Context Protocol. Core capabilities include creating, listing, and deleting databases; creating and updating documents with automatic create/update detection; and retrieving documents. For CouchDB 3.x and later, Mango query features are exposed through tools to create and delete Mango indexes as well as run Mango queries to find documents. The server automatically adapts feature availability based on the detected CouchDB version, enabling Mango-related operations only when supported. To use, run the server with a connected CouchDB instance (via COUCHDB_URL) and then invoke the available MCP tools to perform operations like creating a database, inserting or updating documents, indexing fields for Mango queries, and querying documents using Mango syntax.

Prerequisites:

• Node.js 14 or higher
• npm (comes with Node.js)
• A running CouchDB instance (with credentials if required)

1. Install dependencies

npm install

2. Build the TypeScript server

npm run build

3. (Optional) Run in watch mode for auto-rebuild during development

npm run watch

4. Run the server locally (examples assume a dev environment)

# Ensure COUCHDB_URL and COUCHDB_VERSION are set or use a .env file
export COUCHDB_URL=http://username:password@localhost:5984
export COUCHDB_VERSION=1.7.2
node build/index.js

5. If using Smithery for automated installation (Claude Desktop integration)

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

To configure Claude Desktop with this MCP server, add the following config (adjust the path to your built server):

{
  "mcpServers": {
    "couchdb-mcp-server": {
      "command": "/path/to/couchdb-mcp-server/build/index.js",
      "env": {
        "COUCHDB_URL": "http://username:password@localhost:5984"
      }
    }
  }
}

Note: The exact command may vary depending on how you build and host the server; typically you run the built index.js with Node.

Environment variables:

• COUCHDB_URL: The connection URL for CouchDB (including credentials if required). Defaults to http://localhost:5984.
• COUCHDB_VERSION: The detected CouchDB version to enable features like Mango indexes/queries. Common issues:
• Ensure CouchDB is reachable from the machine running the MCP server.
• If authentication is enabled, provide correct credentials in COUCHDB_URL.
• Mango indices require a compatible CouchDB version (3.x+ for Mango indexing and querying).
• When debugging, MCP servers communicate over stdio; consider using the MCP Inspector for debugging and monitoring.

NPM package name (for Node.js users): @robertoamoreno/couchdb-mcp-server