CouchDB MCP Server

CouchDB MCP Server is an open-source Python Model Context Protocol server for Apache CouchDB.

The project is in early development. Version 0.1.0 Read-Only Preview is implemented in source but has not been published as a release package yet. Published packages and release installation commands should not be assumed to exist until they are documented in a release.

0.1 Scope

Version 0.1.0 Read-Only Preview is a local, strictly read-only MCP server for Apache CouchDB 3.x.

The approved version 0.1 constraints are:

• local stdio MCP transport only;
• one CouchDB instance per server process;
• no writes, administration, replication, attachments, dashboard, embedded AI, or remote MCP server;
• compact, bounded, structured, model-friendly responses;
• security controls enforced by implementation, not only documentation.

See docs/SCOPE_0_1.md for the contributor-facing scope summary.

0.1 Tools

Version 0.1 exposes exactly these nine product tools:

1. get_server_status
2. list_databases
3. get_database_info
4. get_document
5. list_documents
6. query_documents
7. list_indexes
8. explain_query
9. inspect_database_structure

The query_documents implementation supports a safe Mango subset: selector, fields, limit, bookmark, sort, and use_index. It does not expose arbitrary Mango options.

The list_indexes implementation lists Mango index metadata for authorized databases. It does not create, delete, or modify indexes.

The explain_query implementation explains a controlled Mango query plan for an authorized database. It does not return matching documents or expose raw design documents.

The inspect_database_structure implementation infers probable field structure from a bounded document sample. It reports field paths, observed types, occurrence counts, and frequencies without returning example values.

All nine approved version 0.1 tools are implemented in source. Release readiness still depends on packaging, verification, and publication checks.

Not In 0.1

The following are explicitly outside the approved 0.1 scope:

• document creation, updates, deletion, or bulk writes;
• database creation or deletion;
• index creation or deletion;
• user, permission, cluster, compaction, replication, or CouchDB configuration administration;
• arbitrary CouchDB endpoint wrappers such as execute_request, call_endpoint, or send_http_request;
• attachments, revision history browsing, MapReduce views, and continuous changes feeds;
• Streamable HTTP transport, public remote MCP hosting, OAuth, OIDC, SSO, or remote sessions;
• multiple CouchDB instances in one server process;
• dashboard, desktop UI, embedded language model, embeddings, semantic search, autonomous agents, and automatic index creation.

Ideas outside 0.1 should be discussed as future-version candidates rather than implemented directly.

Security Direction

The intended 0.1 security model includes:

• database allowlists applied before CouchDB database requests;
• CouchDB system databases hidden by default;
• TLS certificate verification enabled by default for HTTPS;
• no credentials in MCP responses, exceptions, logs, URLs, snapshots, or committed files;
• response-size, JSON-depth, document-count, timeout, and pagination limits;
• normalized errors without internal stack traces;
• stdout reserved for MCP stdio protocol traffic, with diagnostics sent to stderr.

Documentation

Current project references:

• 0.1 Scope Summary
• Functional Scope 0.1
• Official Vision

Local Development

The Python project skeleton is managed with uv.

Current local checks:

uv sync
uv run ruff format --check .
uv run ruff check .
uv run mypy src tests
uv run pytest

Optional CouchDB integration tests are disabled by default. They require a local CouchDB instance and create then delete a dedicated test database:

$env:COUCHDB_MCP_RUN_INTEGRATION = "1"
$env:COUCHDB_MCP_COUCHDB_URL = "url"
$env:COUCHDB_MCP_COUCHDB_USERNAME = "username"
$env:COUCHDB_MCP_COUCHDB_PASSWORD = "password"
$env:COUCHDB_MCP_INTEGRATION_DATABASE = "couchdb_mcp_tools_integration"
uv run pytest tests/test_couchdb_tools_integration.py
uv run pytest tests/test_mcp_stdio_integration.py

The executable module runs a local stdio MCP server and exposes the nine approved version 0.1 tools.

Compatibility

For version 0.1 public preview, compatibility has been verified with MCP Inspector and the official MCP Python SDK stdio client.

Broader MCP host compatibility remains pending and will be validated after the public preview release.

Configuration

Configuration is loaded from environment variables with the COUCHDB_MCP_ prefix and, for local development, from an optional .env file.

See .env.example for the current configuration surface.

Configuration validates:

• CouchDB base URL without embedded credentials;
• optional username and password, with password treated as a secret;
• database allowlist parsing and validation;
• system database access disabled by default;
• positive limits for documents, schema inspection, response size, JSON depth, and timeout;
• maximum limits greater than or equal to default limits;
• TLS verification enabled by default.

Contributing

Contributions should stay within the approved 0.1 scope unless an explicit product decision changes that scope.

Before proposing a change, read CONTRIBUTING.md and docs/SCOPE_0_1.md.

License

This project is licensed under the Apache License 2.0. See LICENSE.