Provides tools for interacting with Apache CouchDB, enabling operations such as database management (create, list, delete), document manipulation (create, get, update, delete, list), and search using Mango queries and indexing.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@CouchDB MCP Server Search for users with the email 'john@example.com' in the users database"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server that provides tools for interacting with CouchDB databases. This server enables Claude Code and other MCP clients to perform database operations, document management, and search queries on CouchDB instances.
List Databases: View all databases on the CouchDB server
Create Database: Create new databases
Delete Database: Remove databases
Create Document: Insert new documents with optional custom IDs
Get Document: Retrieve documents by ID
Update Document: Modify existing documents
Delete Document: Remove documents
List Documents: View all documents in a database with optional full content
Search Documents: Query documents using CouchDB Mango queries with pagination support
Create Index: Create indexes for better query performance
List Indexes: View all indexes in a database
Related MCP server: Apache CouchDB MCP Server by CData
Python 3.10 or higher
CouchDB server (local or remote)
Claude Code CLI
Clone or download this repository to your local machine.
Install dependencies using uv (recommended):
uv syncOr using pip:
pip install -e .Make sure you have CouchDB installed and running. You can:
Install CouchDB locally:
macOS: brew install couchdb
Ubuntu/Debian: sudo apt-get install couchdb
Or download from couchdb.apache.org
Use Docker:
docker run -d -p 5984:5984 --name couchdb \
-e COUCHDB_USER=admin \
-e COUCHDB_PASSWORD=password \
couchdb:latestAccess CouchDB:
Default URL: http://localhost:5984
Web UI (Fauxton): http://localhost:5984/_utils
To use this MCP server with Claude Code, you need to add it to your Claude Code configuration file.
The Claude Code configuration file is located at:
macOS/Linux: ~/.config/claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Open or create the configuration file:
# macOS/Linux
mkdir -p ~/.config/claude
nano ~/.config/claude/claude_desktop_config.jsonAdd the CouchDB MCP server to the mcpServers section:
Using uv (recommended):
{
"mcpServers": {
"couchdb": {
"command": "uv",
"args": [
"run",
"--directory", "/path/to/couchdb_mcp",
"python", "couchdb_mcp_server.py"
],
"env": {
"COUCHDB_URL": "http://localhost:5984"
}
}
}
}Using python directly (requires manual dependency install):
{
"mcpServers": {
"couchdb": {
"command": "python",
"args": [
"/path/to/couchdb_mcp_server.py"
],
"env": {
"COUCHDB_URL": "http://localhost:5984"
}
}
}
}For authenticated CouchDB instances, include credentials in the URL:
{
"mcpServers": {
"couchdb": {
"command": "uv",
"args": [
"run",
"--directory", "/path/to/couchdb_mcp",
"python", "couchdb_mcp_server.py"
],
"env": {
"COUCHDB_URL": "http://admin:password@localhost:5984"
}
}
}
}For remote CouchDB servers:
{
"mcpServers": {
"couchdb": {
"command": "uv",
"args": [
"run",
"--directory", "/path/to/couchdb_mcp",
"python", "couchdb_mcp_server.py"
],
"env": {
"COUCHDB_URL": "https://username:password@your-server.com:5984"
}
}
}
}Save the configuration file and restart Claude Code.
Once configured, you can use Claude Code to interact with your CouchDB instance. Here are some example requests:
Create a new database called "users"List all databasesDelete the database named "test_db"Create a document in the users database with data: {"name": "John Doe", "email": "john@example.com"}Get the document with ID "user123" from the users databaseUpdate document user123 in users database with new email addressList all documents in the users databaseSearch the users database for all documents where name equals "John Doe"Search for documents in the products database where price is greater than 100Lists all databases on the CouchDB server.
Parameters: None
Creates a new database.
Parameters:
name (string, required): Name of the database to create
Deletes a database.
Parameters:
name (string, required): Name of the database to delete
Creates a new document in a database.
Parameters:
database (string, required): Name of the database
document (object, required): Document data as JSON object
doc_id (string, optional): Document ID (auto-generated if not provided)
Retrieves a document from a database.
Parameters:
database (string, required): Name of the database
doc_id (string, required): Document ID
Updates an existing document.
Parameters:
database (string, required): Name of the database
doc_id (string, required): Document ID
document (object, required): Updated document data (must include _rev)
Deletes a document from a database.
Parameters:
database (string, required): Name of the database
doc_id (string, required): Document ID
rev (string, required): Document revision (_rev)
Searches for documents using Mango queries.
Parameters:
database (string, required): Name of the database
query (object, required): Mango query selector (e.g., {"name": "John"})
limit (integer, optional): Maximum number of documents to return (default: 25)
skip (integer, optional): Number of documents to skip (default: 0)
Lists all documents in a database.
Parameters:
database (string, required): Name of the database
limit (integer, optional): Maximum number of documents to return
include_docs (boolean, optional): Include full document content (default: false)
Creates an index to dramatically improve Mango query performance.
Parameters:
database (string, required): Name of the database
fields (array, required): Fields to index (e.g., ["type", "name"])
index_name (string, optional): Name for the index
Note: While indexes are optional, they are highly recommended. Without indexes, CouchDB scans all documents which can be very slow on large databases.
Lists all indexes in a database.
Parameters:
database (string, required): Name of the database
CouchDB's Mango query system (couchdb_search_documents) does not require indexes, but they are strongly recommended for performance.
According to the CouchDB documentation:
Without an index, CouchDB falls back to scanning all documents (_all_docs)
This works but "can be arbitrarily slow" on large databases
Creating indexes dramatically improves query performance
When to create indexes:
Your database has many documents (>1000)
Queries are slow
You frequently query the same fields
When you can skip indexes:
Small databases (<100 documents)
Infrequent queries
You don't mind slower response times
Example:
1. Try searching: "Search omnibot database where type equals 'name'"
2. If it works but is slow, create an index: "Create an index on the 'type' field in omnibot database"
3. Future queries will be much fasterIf you see connection errors:
Verify CouchDB is running: curl http://localhost:5984
Check the URL in your configuration
Verify credentials if using authentication
Check firewall settings for remote connections
If you see permission errors:
Ensure the user has appropriate CouchDB permissions
Check that the database exists before performing document operations
Verify document revisions (_rev) when updating or deleting
If you're searching for documents but getting no results:
Verify documents exist: Use couchdb_list_documents with include_docs: true to see actual document structure
Check field names match exactly: Field names are case-sensitive ("Type" ≠ "type")
Verify field values match: Values are also case-sensitive ("Name" ≠ "name")
Check the field exists: Queries only match documents where the field is present
Consider creating an index: While not required, indexes ensure queries work reliably and quickly
If Claude Code doesn't recognize the CouchDB tools:
Verify the configuration file path is correct
Ensure the --directory path (uv) or Python script path is absolute, not relative
Restart Claude Code after configuration changes
Check that dependencies are installed (uv sync or pip install -e .)
Mango queries use MongoDB-style selectors:
Equality:
{"name": "John Doe"}Comparison:
{"age": {"$gt": 18}}Multiple conditions:
{"$and": [{"age": {"$gte": 18}}, {"status": "active"}]}Pattern matching:
{"email": {"$regex": ".*@example\\.com$"}}MIT License
Contributions are welcome! Please feel free to submit issues or pull requests.
Create a new database
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the database to create |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'Create a new database' which implies a write/mutation operation, but doesn't describe what happens on success/failure, permissions required, or side effects (e.g., if it overwrites existing databases). For a mutation tool with zero annotation coverage, this is inadequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's appropriately sized for a simple tool and front-loads the core action. Every word earns its place, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a database creation tool (a mutation with potential side effects), no annotations, and no output schema, the description is incomplete. It doesn't address behavioral aspects like error conditions, idempotency, or what is returned. The agent lacks sufficient context to use this tool safely and effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no parameter information beyond what the schema provides. However, with 100% schema description coverage (the 'name' parameter is fully documented in the schema), the baseline is 3. The description doesn't compensate with additional context like naming conventions or constraints, but doesn't need to given the comprehensive schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'new database', making the purpose immediately understandable. It distinguishes from siblings like 'couchdb_create_document' by specifying the database resource type. However, it doesn't explicitly contrast with 'couchdb_list_databases' or 'couchdb_delete_database', which would have made it a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., whether the database must not already exist), when not to use it, or direct comparisons to siblings like 'couchdb_list_databases' for checking existing databases first. This leaves the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new document in a database
| Name | Required | Description | Default |
|---|---|---|---|
| database | Yes | Name of the database | |
| document | Yes | Document data as JSON object | |
| doc_id | No | Optional document ID (if not provided, CouchDB generates one) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral insight. It states 'Create' which implies a write/mutation operation, but doesn't disclose permissions needed, whether it's idempotent, error conditions, or what happens on success (e.g., returns document ID). This leaves significant gaps for agent understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with zero wasted words. It's appropriately front-loaded with the core action and resource, making it efficient for quick comprehension without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what happens after creation (e.g., returns document ID or confirmation), error handling, or how it differs from similar tools like couchdb_update_document. Given the complexity and lack of structured data, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are well-documented in the schema itself. The description adds no additional parameter semantics beyond implying 'document' is JSON data, which is already clear from the schema. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and resource ('new document in a database'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like couchdb_update_document or couchdb_get_document, which would require mentioning this is specifically for initial creation rather than modification or retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., database must exist), when to choose this over couchdb_update_document for updates, or any context about sibling tools like couchdb_create_database for database-level operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an index to improve Mango query performance. While optional, indexes dramatically speed up queries and ensure reliable results.
| Name | Required | Description | Default |
|---|---|---|---|
| database | Yes | Name of the database | |
| fields | Yes | Fields to index (e.g., ['type', 'name']) | |
| index_name | No | Optional name for the index |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. While it mentions performance benefits, it doesn't disclose important behavioral traits like whether this is a write operation, what permissions are required, whether indexes are permanent or can be deleted, or any rate limits. The description is insufficient for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences that each earn their place. The first states the core purpose, and the second provides important context about benefits. No wasted words or unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool (creating indexes) with no annotations and no output schema, the description is incomplete. It doesn't explain what happens after index creation, whether there are side effects, what the response looks like, or any error conditions. The performance benefit mention is helpful but insufficient for full contextual understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters. The description doesn't add any parameter-specific information beyond what's in the schema. The baseline of 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('create') and resource ('index') with specific purpose ('to improve Mango query performance'). It distinguishes from siblings like couchdb_create_database and couchdb_create_document by focusing on indexes rather than databases or documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when to use this tool ('to improve Mango query performance') and indicates it's optional but beneficial. However, it doesn't explicitly state when NOT to use it or mention specific alternatives among the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a database
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the database to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Delete a database' implies a destructive mutation, but it fails to specify critical details: whether deletion is permanent, if it requires admin permissions, what happens to contained documents, or error conditions. This is inadequate for a high-risk operation with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at three words, with zero wasted language. It's front-loaded with the core action and resource, making it easy to parse quickly. Every word earns its place by directly conveying the tool's function without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high complexity of a destructive database deletion tool with no annotations and no output schema, the description is incomplete. It lacks essential context: behavioral risks, permission requirements, error handling, and what happens post-deletion. For such a critical operation, this minimal description fails to provide adequate guidance for safe and correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'name' parameter clearly documented as 'Name of the database to delete'. The description adds no additional semantic context beyond this, such as format constraints or examples. Since the schema does the heavy lifting, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the resource ('a database'), making the purpose immediately understandable. It distinguishes this from sibling tools like 'couchdb_delete_document' by specifying the database-level operation. However, it lacks specificity about what 'delete' entails (e.g., permanent removal vs. soft delete), which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., database must exist), consequences (e.g., all documents lost), or sibling tools like 'couchdb_list_databases' for verification. Without such context, an agent might misuse it without understanding the implications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a document from a database
| Name | Required | Description | Default |
|---|---|---|---|
| database | Yes | Name of the database | |
| doc_id | Yes | Document ID | |
| rev | Yes | Document revision (_rev) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral insight. It states this is a deletion operation but doesn't clarify if it's permanent, reversible, requires specific permissions, has side effects, or what happens on failure. For a destructive operation, this is inadequate disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise - a single clear sentence with no wasted words. It's front-loaded with the core action and resource, making it efficient for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no annotations and no output schema, the description is insufficient. It doesn't explain what 'delete' means in this context (permanent removal?), what permissions are required, what the response looks like, or error conditions. Given the complexity and risk of document deletion, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all three parameters. The description adds no additional parameter context beyond what's in the schema, maintaining the baseline score of 3 for adequate but not enhanced parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and resource ('a document from a database'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'couchdb_delete_database' or specify what type of document deletion this performs (permanent vs soft).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. The description doesn't mention prerequisites (like needing a valid revision), when not to use it, or how it differs from related tools like 'couchdb_update_document' for document modifications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a document from a database
| Name | Required | Description | Default |
|---|---|---|---|
| database | Yes | Name of the database | |
| doc_id | Yes | Document ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the operation is a retrieval, implying read-only behavior, but doesn't disclose error conditions (e.g., missing database/document), authentication needs, rate limits, or return format. For a tool with no annotations, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with zero waste. It's appropriately sized for a simple retrieval tool and front-loads the core action, making it easy to understand at a glance without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is incomplete. It doesn't explain what a 'document' returns (e.g., JSON object with _id, _rev), error handling, or how it differs from sibling tools. For a retrieval tool in a set with multiple document-related operations, more context is needed to guide proper use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters ('database' and 'doc_id') adequately. The description adds no additional meaning beyond what the schema provides, such as format examples or constraints, which aligns with the baseline score when schema coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('retrieve') and resource ('a document from a database'), which clarifies the basic purpose. However, it lacks specificity about what a 'document' entails in CouchDB context and doesn't differentiate from sibling tools like 'couchdb_list_documents' or 'couchdb_search_documents' that also retrieve documents in different ways.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. The description doesn't mention that this retrieves a single document by ID, unlike 'couchdb_list_documents' (lists multiple) or 'couchdb_search_documents' (searches by criteria), nor does it specify prerequisites like database existence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all databases in the CouchDB server
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states it's a list operation, implying read-only behavior, but doesn't specify details like whether it returns all databases at once (vs. paginated), requires authentication, has rate limits, or what format the output takes. This is inadequate for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with zero wasted words. It's front-loaded with the core action and resource, making it efficient and easy to parse. Every part of the sentence contributes directly to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema), the description is minimal but incomplete. It lacks behavioral context (e.g., output format, authentication needs) and usage guidelines, which are important even for simple tools. Without annotations or output schema, the description should provide more completeness for the agent to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the schema already fully documents the lack of inputs. The description doesn't need to add parameter details, and it correctly implies no inputs are required. A baseline of 4 is appropriate as it doesn't mislead about parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all') and resource ('databases in the CouchDB server'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'couchdb_list_documents' or 'couchdb_list_indexes', which would require mentioning it's specifically about databases rather than documents or indexes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., server connectivity), context for usage (e.g., before creating/deleting databases), or comparisons to siblings like 'couchdb_search_documents' for filtered queries. This leaves the agent with minimal direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all documents in a database with their IDs and revisions
| Name | Required | Description | Default |
|---|---|---|---|
| database | Yes | Name of the database | |
| limit | No | Maximum number of documents to return | |
| include_docs | No | Include full document content (default: false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the tool lists documents with IDs and revisions, implying a read-only operation, but fails to detail critical aspects like pagination behavior, error handling, or performance considerations (e.g., impact of include_docs on response size). This leaves significant gaps for a tool with parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary details. It is front-loaded and wastes no words, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 parameters, no output schema, and no annotations), the description is insufficient. It lacks information on return values (e.g., format of listed documents), error cases, or how parameters interact, leaving the agent with incomplete guidance for proper invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema fully documents parameters like database, limit, and include_docs. The description adds no additional semantic context beyond what the schema provides, such as explaining default behaviors or constraints, resulting in a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('all documents in a database'), specifying the output includes IDs and revisions. However, it doesn't explicitly differentiate from sibling tools like couchdb_search_documents or couchdb_get_document, which could also retrieve documents but with different scopes or methods.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like couchdb_search_documents or couchdb_get_document. It lacks context about use cases, such as retrieving a comprehensive list versus filtered searches, leaving the agent to infer usage based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all indexes in a database
| Name | Required | Description | Default |
|---|---|---|---|
| database | Yes | Name of the database |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. While 'List all indexes' implies a read-only operation, it doesn't specify whether this requires specific permissions, what format the output takes (e.g., JSON array), or any limitations (e.g., pagination, rate limits). The description is minimal and lacks essential context for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's front-loaded with the core purpose and appropriately sized for a simple list operation, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., index definitions, status), error conditions, or behavioral nuances. For a tool that likely returns structured data about indexes, more context is needed to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the single parameter 'database' clearly documented. The description adds no additional meaning beyond what the schema provides (e.g., it doesn't clarify database naming conventions or constraints). With high schema coverage, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all indexes') and the resource ('in a database'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'couchdb_list_databases' or 'couchdb_list_documents', which follow similar naming patterns but target different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., database must exist), exclusions, or how it relates to sibling tools like 'couchdb_create_index' or 'couchdb_search_documents' that might involve indexes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for documents in a database using a Mango query. Works without indexes but creating indexes (via couchdb_create_index) improves performance significantly.
| Name | Required | Description | Default |
|---|---|---|---|
| database | Yes | Name of the database | |
| query | Yes | Mango query selector (e.g., {'name': 'John'} for exact match, {'age': {'$gt': 18}} for comparisons) | |
| limit | No | Maximum number of documents to return (default: 25) | |
| skip | No | Number of documents to skip (default: 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that the tool 'works without indexes' but performance improves with indexing, which is valuable behavioral context. However, it doesn't mention other important traits like read/write nature (implied read-only but not stated), potential rate limits, error conditions, or what happens with large result sets beyond the limit parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that are front-loaded with the core purpose. The first sentence states exactly what the tool does, and the second provides important performance context. Every sentence earns its place with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 4 parameters, 100% schema coverage, but no annotations and no output schema, the description is adequate but has gaps. It covers the basic purpose and performance considerations but doesn't address what the tool returns (no output schema) or other behavioral aspects. Given the complexity, it should ideally mention more about the return format or error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema - it mentions Mango queries but doesn't provide additional semantic context about parameters. The baseline of 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Search for documents') and resource ('in a database'), using the precise method ('using a Mango query'). It distinguishes from siblings like couchdb_list_documents (which likely lists all documents without querying) and couchdb_get_document (which retrieves a single document by ID).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when to use this tool (for searching with Mango queries) and mentions performance considerations (indexing via couchdb_create_index). However, it doesn't explicitly state when NOT to use it or directly compare it to alternatives like couchdb_list_documents for simpler listing needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing document in a database
| Name | Required | Description | Default |
|---|---|---|---|
| database | Yes | Name of the database | |
| doc_id | Yes | Document ID | |
| document | Yes | Updated document data (must include _rev) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool updates documents but doesn't mention critical behaviors like whether it's idempotent, what happens on conflicts, if it requires specific permissions, or what the response format is. This is inadequate for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's function without any unnecessary words. It's appropriately sized and front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a document update tool with no annotations and no output schema, the description is insufficient. It doesn't cover behavioral aspects like error conditions, response format, or idempotency, leaving significant gaps in understanding how to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all three parameters. The description adds no additional parameter semantics beyond what's in the schema (e.g., it doesn't explain the '_rev' requirement in more detail). This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'an existing document in a database', making the purpose unambiguous. However, it doesn't distinguish this tool from its sibling 'couchdb_delete_document' or 'couchdb_get_document' in terms of operation type, which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'couchdb_create_document' or 'couchdb_delete_document'. It lacks context about prerequisites (e.g., document must exist) or typical use cases, offering only basic functional information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every tool has a clearly distinct purpose targeting specific resources and actions in the CouchDB domain. The tools are well-differentiated by their object types (database, document, index) and operations (create, delete, get, list, search, update), with no ambiguous overlaps that would cause misselection.
All tools follow a perfectly consistent naming pattern: 'couchdb_' prefix followed by a verb (create, delete, get, list, search, update) and a noun (database, document, index). This uniform snake_case convention makes the tool set predictable and easy to navigate.
With 11 tools, this server is well-scoped for CouchDB operations, covering core database and document management. Each tool earns its place by addressing a specific, necessary function without redundancy, making the count appropriate for the domain.
The tool set provides complete CRUD/lifecycle coverage for databases, documents, and indexes, including creation, retrieval, updating, deletion, listing, and searching. There are no obvious gaps or dead ends, enabling agents to handle all essential CouchDB workflows effectively.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Query, join, profile, clean and convert CSV/JSON/Parquet with server-side DuckDB over MCP.
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/andyfe76/couchdb_mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
