Robertoamoreno Couchdb MCP Server

🚀 CouchDB-MCP-Server

A Model Context Protocol (MCP) server for interacting with CouchDB.

This is an MCP server built on TypeScript, providing tools for managing CouchDB databases and documents. It enables AI assistants to interact with CouchDB through a simple interface.

✨ Features

Tools

Basic Tools (All CouchDB Versions)

• createDatabase - Create a new CouchDB database

  • Accepts 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

  • Receives dbName as a required parameter
  • Removes the specified database and all its documents

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

  • Required parameters:
    • dbName: Database name
    • docId: Document ID
    • data: Document data (JSON object)
      • When updating, includes the _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 whether to create or update based on the presence of the _rev field

• getDocument - Retrieve a document from the database

  • Required parameters:
    • dbName: Database name
    • docId: Document ID
  • Returns the document content

Mango Query Tools (CouchDB 3.x and above)

• createMangoIndex - Create a new Mango index

  • Required parameters:
    • dbName: Database name
    • indexName: Index name
    • fields: Array of fields to index
  • Creates a new index for efficient queries

• deleteMangoIndex - Delete a Mango index

  • Required parameters:
    • dbName: Database name
    • designDoc: Design document name
    • indexName: Index name
  • Removes the specified index

• listIndexes - List all indexes

  • Returns information about all indexes in the database

📚 Version Support

This server enables different features based on the CouchDB version:

• Runs on CouchDB 2.x and above
• Automatically enables corresponding features based on the detected CouchDB version

🔧 Configuration

Configure the server using the following environment variables:

COUCHDB_URL=http://localhost:5984
COUCHDB_VERSION=3.0.1

By default, the server connects to a locally running CouchDB instance.

📦 Installation and Development

Install Dependencies

npm install

Build

npm run build

Run Tests

npm test

Debug

Start the debugging tool using the following command:

npm run debug

🚀 Installation via Smithery

Install the server on the Smithery platform using the following command:

smith install @robertoamoreno/couchdb-mcp-server

🚫 Error Handling

This server includes powerful error handling capabilities, covering common scenarios:

• Invalid database names or document IDs
• Non-existent or already existing databases
• Connection issues
• Authentication failures
• Invalid document data

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