PeerDB MCP

Inspect replication pipelines, investigate sync errors, and manage CDC mirrors from your AI client.

PeerDB MCP connects your Model Context Protocol client to the PeerDB Flow REST API. Ask about pipeline status, review recent errors and batches, or request a pipeline change using 13 typed tools.

Community preview. MCP integration and API contract tests use a simulated gateway; live PeerDB compatibility is still being validated. Reports from real setups are welcome. This is an independent community project.

Quick start · Client setup · Tool reference · Troubleshooting · Contributing

What you can do

You can also validate and create CDC mirrors, resume paused pipelines, and update batch size, idle timeout, snapshot settings, or table mappings. Diagnostics return evidence and possible next steps; they do not automatically repair replication.

Related MCP server: QuestLLens

Quick start

You need a reachable PeerDB Flow REST gateway, uv (which includes uvx), Git, and an MCP client that supports stdio. The server uses Python 3.11+; uv can provision a compatible Python when needed.

Add this to your client's MCP configuration. It starts in read-only mode:

{
  "mcpServers": {
    "peerdb": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/AMohammadzadeh/peerdb-mcp.git@main",
        "peerdb-mcp"
      ],
      "env": {
        "PEERDB_URL": "http://localhost:8113",
        "PEERDB_READ_ONLY": "true"
      }
    }
  }
}

Restart your client, then ask:

Check the PeerDB version, then list my pipelines. Do not change anything.

The client installs and launches the server automatically. localhost refers to the computer running the MCP process. Point the URL at the REST gateway; PeerDB's UI and gRPC ports serve different interfaces. Port 8113 is a common self-hosted gateway port—check your deployment.

For client-specific instructions, see Claude Desktop, Claude Code, Cursor, and Codex. For a fixed revision, replace @main with a full commit SHA. Installation currently uses GitHub; the package has not been published to PyPI.

Authentication

Set credentials through your client's environment or secure secret mechanism:

Choose one authentication method. See the configuration reference for examples and all environment variables. Use HTTPS for remote authenticated gateways. Pipeline logs and configuration are returned to your MCP client and may be sent to its model provider; review your client's data handling before use.

Enable pipeline changes

Set PEERDB_READ_ONLY to false and restart the MCP process to enable creation, pause, resume, and updates. The quick start explicitly enables read-only mode; the application's default when this variable is omitted is false.

Changes are asynchronous. An accepted request does not mean the operation has finished; check pipeline status afterward. See operation behavior.

Supported operations

Peer creation, pipeline deletion, and automatic resync are not exposed. Managed ClickPipes compatibility has not been verified. Read the tool reference for arguments and API compatibility notes for the upstream source checked.

Verify your local setup

From a checkout on a computer that can reach PeerDB:

git clone https://github.com/AMohammadzadeh/peerdb-mcp.git
cd peerdb-mcp
uv sync --frozen
export PEERDB_URL=http://localhost:8113
uv run --frozen python -m peerdb_mcp.smoke --pipeline YOUR_EXISTING_MIRROR

Inject authentication variables if required. Omit --pipeline to check only MCP startup, version, and pipeline listing. The test forces read-only mode and prints a summary without URLs, credentials, pipeline names, or log contents. Failed or partial checks return a nonzero exit status. Passing checks establish API access, not replication health.

Feedback and contributions

Trying this with PeerDB? Report your results with your PeerDB version, MCP client, and a sanitized smoke-test summary. Please remove credentials and private data from anything you share.

Bug fixes, compatibility reports, documentation improvements, and focused feature requests are welcome. Start with CONTRIBUTING.md for development commands and the API contract conventions.

License

PeerDB MCP is available under the MIT License.