Couchdb

You can manage CouchDB databases and documents from an MCP client by using a TypeScript MCP server that exposes a straightforward set of tools. This server adapts to your CouchDB version, automatically enabling Mango support when available, and lets you perform common operations with reliable error handling.

How to use

Interact with the server through an MCP client to perform core CouchDB operations. You can create and delete databases, create or update documents, fetch documents, and, on CouchDB 3.x and later, manage Mango indexes and run Mango queries. The server automatically detects the CouchDB version and exposes the appropriate features.

How to install

Prerequisites are Node.js 14 or higher and a running CouchDB instance with appropriate credentials if authentication is enabled.

Install dependencies and build the server locally so you can run it on your machine.

Install dependencies and build the server.

npm install

Build the server for production or local development.

npm run build

For development with automatic rebuild on file changes, run the watcher.

npm run watch

If you want to debug MCP interactions, you can use the Inspector tool to access debugging utilities in your browser.

npm run inspector

Additional configuration and startup example

Configure how the MCP server connects to CouchDB and, if you use the provided local runtime, how to start the server. The following example shows a local startup configuration you can place in your MCP config.

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

Notes on usage patterns

• Use createDatabase to create a new database, listDatabases to view all databases, and deleteDatabase to remove one along with its documents.

• Use createDocument to add a new document or update an existing one. Include the _rev field for updates. The server automatically detects create versus update based on the presence of _rev.

• Use getDocument to fetch a document by its ID. For Mango operations on CouchDB 3.x+, you can create or delete Mango indexes with createMangoIndex and deleteMangoIndex, list them with listMangoIndexes, and query documents with findDocuments.

Error handling and debugging

The server includes robust error handling for common issues such as invalid database names, missing documents, conflicts due to revisions, connectivity problems, and authentication failures. When an error occurs, you receive a clear MCP-formatted error with codes and messages to guide remediation.

Security and best practices

Secure your CouchDB endpoint with proper credentials and limit access to trusted MCP clients. When running the server in a shared environment, use environment variables to avoid hard-coding sensitive information in your configuration files.

Troubleshooting

If you encounter startup or runtime issues, verify that CouchDB is reachable at the URL specified by COUCHDB_URL, that the version is compatible, and that the runtime command path is correct for your environment. Check logs produced by the Inspector tool for debugging details.

Available tools

createDatabase

Create a new CouchDB database. Requires dbName. Creates the database if it does not exist.

listDatabases

List all CouchDB databases. Returns an array of database names.

deleteDatabase

Delete a CouchDB database. Requires dbName. Removes the specified database and all its documents.

createDocument

Create a new document or update an existing one in a database. Requires dbName, docId, and data. Uses _rev to distinguish updates; returns the document ID and new or updated revision.

getDocument

Retrieve a document from a database. Requires dbName and docId. Returns the document content.

createMangoIndex

Create a Mango index for efficient querying. Requires dbName, indexName, and fields.

deleteMangoIndex

Delete a Mango index. Requires dbName, designDoc, and indexName.

listMangoIndexes

List all Mango indexes in a database. Requires dbName.

findDocuments

Query documents using Mango query syntax. Requires dbName and query.