Install the MCP server

The TwinCommit MCP server is the npm package @twincommit/mcp. You do not install it globally: each client starts it with npx. All it needs is the URL of a running TwinCommit pipeline’s metrics address.

Requirements

Node.js 20 or later on the machine running your AI client
Network access to the TwinCommit metrics_addr (default port 9108)

Add it to your client

claude mcp add twincommit -- npx -y @twincommit/mcp

With a remote pipeline and a token:

claude mcp add twincommit \
  -e TWINCOMMIT_URL=https://replication.internal:9108 \
  -e TWINCOMMIT_TOKEN=$TWINCOMMIT_TOKEN \
  -- npx -y @twincommit/mcp

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "twincommit": {
      "command": "npx",
      "args": ["-y", "@twincommit/mcp"],
      "env": { "TWINCOMMIT_URL": "http://localhost:9108" }
    }
  }
}

Restart Claude Desktop. The TwinCommit tools appear in the tools menu.

code --add-mcp '{"name":"twincommit","command":"npx","args":["-y","@twincommit/mcp"]}'

Or add it to .vscode/mcp.json to share with your team:

{
  "servers": {
    "twincommit": {
      "command": "npx",
      "args": ["-y", "@twincommit/mcp"],
      "env": { "TWINCOMMIT_URL": "http://localhost:9108" }
    }
  }
}

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "twincommit": { "command": "npx", "args": ["-y", "@twincommit/mcp"] }
  }
}

Environment variables

Variable	Default	Description
`TWINCOMMIT_URL`	`http://localhost:9108`	Metrics address of a pipeline. Comma-separate several URLs to manage several pipelines.
`TWINCOMMIT_TOKEN`	none	Bearer token, if `control.token` is set on the pipeline
`TWINCOMMIT_PROMETHEUS_URL`	none	Prometheus base URL, used by `get_lag` for history
`TWINCOMMIT_MCP_ALLOW_WRITES`	`false`	Set to `true` to enable `start_pipeline`, `stop_pipeline` and `resnapshot_table`
`TWINCOMMIT_MCP_ALLOW_ROW_VALUES`	`false`	Set to `true` to include column values in `tail_events`
`TWINCOMMIT_MCP_AUDIT_LOG`	`~/.twincommit/mcp-audit.log`	Where tool calls are recorded

Check it works

Ask your assistant:

List my TwinCommit pipelines and their lag.

It should call list_pipelines and answer with each pipeline’s state.