Dolt MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with direct access to Dolt and DoltgreSQL databases. This server enables AI tools like Claude to interact with Dolt's version-controlled SQL databases over either the MySQL or PostgreSQL wire protocol, allowing for database operations, version control workflows, and data management tasks.

Overview

The Dolt MCP Server acts as a bridge between AI assistants and Dolt databases, exposing a comprehensive set of tools for:

• Database Management: Create, drop, and manage databases
• Table Operations: Create, alter, drop, describe, and query tables
• Version Control: Branch management, commits, merges, and diffs
• Data Operations: Insert, update, delete, and query data
• Remote Operations: Clone, fetch, push, and pull from remote repositories

Both Dolt (MySQL-compatible) and DoltgreSQL (PostgreSQL-compatible) backends are supported. The SQL dialect is selected at startup with the --dolt or --doltgres flag. An embedded DoltLite backend (--doltlite) is also available in specially built binaries, running against a local database file with no server at all — see DoltLite Mode.

Installation

Prerequisites

• Go 1.25 or later
• A running Dolt or DoltgreSQL SQL server instance (not needed for DoltLite mode)

Building from Source

The default build is pure Go (no cgo) and cross-compiles freely:

git clone https://github.com/dolthub/dolt-mcp
cd dolt-mcp
go build -o dolt-mcp-server ./mcp/cmd/dolt-mcp-server

Binaries built this way do not include DoltLite support (--doltlite returns an error). Building with embedded DoltLite requires cgo and libdoltlite; see Building with DoltLite Support.

Docker Installation

Pull the official Docker image:

docker pull dolthub/dolt-mcp:latest

Usage

The Dolt MCP Server can run in two modes and supports multiple deployment methods:

Docker Usage (Recommended for Production)

HTTP Server with Docker

docker run -d \
  --name dolt-mcp-server \
  -p 8080:8080 \
  -e MCP_MODE=http \
  -e DOLT_HOST=your-dolt-host \
  -e DOLT_USER=root \
  -e DOLT_DATABASE=your_database \
  -e DOLT_PASSWORD=your_password \
  dolthub/dolt-mcp:latest

Stdio Server with Docker

docker run -it --rm \
  -e MCP_MODE=stdio \
  -e DOLT_HOST=your-dolt-host \
  -e DOLT_USER=root \
  -e DOLT_DATABASE=your_database \
  -e DOLT_PASSWORD=your_password \
  dolthub/dolt-mcp:latest

Connecting to DoltgreSQL from Docker

Set MCP_DIALECT=doltgres to point the container at a DoltgreSQL server. DOLT_PORT defaults to 5432 when the dialect is doltgres.

docker run -d \
  --name dolt-mcp-server \
  -p 8080:8080 \
  -e MCP_MODE=http \
  -e MCP_DIALECT=doltgres \
  -e DOLT_HOST=your-doltgres-host \
  -e DOLT_USER=postgres \
  -e DOLT_DATABASE=your_database \
  -e DOLT_PASSWORD=your_password \
  dolthub/dolt-mcp:latest

Native Binary Usage

1. Stdio Server (Recommended for AI Assistants)

The stdio server communicates over standard input/output, making it ideal for integration with AI assistants like Claude Desktop.

Against Dolt (MySQL dialect, the default):

./dolt-mcp-server \
  --stdio \
  --dolt \
  --host 0.0.0.0 \
  --port 3306 \
  --user root \
  --database mydb

Against DoltgreSQL (PostgreSQL dialect):

./dolt-mcp-server \
  --stdio \
  --doltgres \
  --host 0.0.0.0 \
  --port 5432 \
  --user postgres \
  --database mydb

If --port is omitted, it defaults to 3306 for Dolt and 5432 for DoltgreSQL.

Claude Desktop Configuration

Add this configuration to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "dolt-mcp": {
      "command": "/path/to/dolt-mcp-server",
      "args": [
        "--stdio",
        "--dolt",
        "--host", "0.0.0.0",
        "--port", "3306",
        "--user", "root",
        "--database", "your_database_name"
      ],
      "env": {
        "DOLT_PASSWORD": "your_password_if_needed"
      }
    }
  }
}

For a DoltgreSQL backend, swap --dolt for --doltgres and adjust the port/user to match your server.

HTTP Client Configuration

When connecting to a Dolt MCP server running in HTTP mode, you can configure Claude to use the HTTP transport. Important: HTTP connections require the /mcp endpoint to be appended to the server URL.

Using Claude CLI

claude mcp add --transport http dolt-mcp https://your-dolt-host:8080/mcp --header "Authorization: Bearer <token>"

Claude Desktop Configuration

Add this configuration to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "dolt-mcp": {
      "transport": "http",
      "url": "https://your-dolt-host:8080/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Note: Replace your-dolt-host, the port, and <your-token> with your actual server details. The /mcp endpoint is required for HTTP connections.

2. HTTP Server

The HTTP server exposes a REST API for MCP tool calls, useful for web applications and custom integrations.

./dolt-mcp-server \
  --http \
  --mcp-port 8080 \
  --dolt \
  --host 0.0.0.0 \
  --port 3306 \
  --user root \
  --database mydb

Pass --doltgres in place of --dolt to connect to a DoltgreSQL server.

DoltLite Mode (Embedded)

DoltLite is a fork of SQLite that adds Dolt's version control features: an entire version-controlled database — branches, commits, diffs, merges, and remotes — lives in a single local file. In DoltLite mode the MCP server embeds the database engine directly, so there is no Dolt or DoltgreSQL server to install, configure, or run: point the server at a database file (created on first use if missing) and start working. This makes it ideal for local-first AI workflows on a laptop or in a container.

DoltLite mode requires a binary built with DoltLite support. Prebuilt archives named dolt-mcp-server-doltlite-<platform> are attached to releases for Linux and macOS on amd64/arm64, plus Windows x64, and the multi-architecture dolthub/dolt-mcp:<version>-doltlite Docker images include it. The default (pure Go) build does not: passing --doltlite to it errors with this binary was built without DoltLite support; rebuild with -tags "doltlite libsqlite3" ....

Quick Start with Docker

docker run -d \
  --name dolt-mcp-server-doltlite \
  -p 8080:8080 \
  -v dolt_mcp_data:/data \
  -e MCP_MODE=http \
  -e DOLT_DB_FILE=/data/mydb.db \
  -e DOLT_COMMIT_NAME="Your Name" \
  -e DOLT_COMMIT_EMAIL=you@example.com \
  dolthub/dolt-mcp:latest-doltlite

Mount a volume at /data so the database file persists across container restarts. See docker/README.md for the full set of environment variables.

Quick Start with a Native Binary

Download a dolt-mcp-server-doltlite archive from the releases page (or build it yourself, below), then:

./dolt-mcp-server-doltlite \
  --doltlite \
  --db-file /path/to/mydb.db \
  --commit-name "Your Name" \
  --commit-email you@example.com \
  --doltlite-busy-timeout 30s \
  --http --mcp-port 8080
# or --stdio in place of --http --mcp-port

No --host, --port, --user, --password, or TLS flags are needed — DoltLite runs in-process against the file.

DoltLite Flags

• --doltlite: Use the embedded DoltLite dialect. Mutually exclusive with --dolt and --doltgres.
• --db-file: Path to the DoltLite database file (required with --doltlite). The file is created if it does not exist.
• --commit-name / --commit-email: The author name and email used for Dolt commits. Recommended — commits are authored as "doltlite" when unset.
• --doltlite-busy-timeout: How long DoltLite waits for a conflicting lock (default 5s; 0 disables waiting).

Claude Desktop Configuration (DoltLite)

{
  "mcpServers": {
    "dolt-mcp-doltlite": {
      "command": "/path/to/dolt-mcp-server-doltlite",
      "args": [
        "--stdio",
        "--doltlite",
        "--db-file", "/path/to/mydb.db",
        "--commit-name", "Your Name",
        "--commit-email", "you@example.com"
      ]
    }
  }
}

Building with DoltLite Support

DoltLite support requires cgo, the doltlite and libsqlite3 build tags, and libdoltlite (with zlib and pthreads). Because of cgo, DoltLite binaries cannot be cross-compiled — build on the target platform.

Get libdoltlite either way:

1. GitHub release zips: download the doltlite-lib-<platform>-<version>.zip asset (e.g. doltlite-lib-linux-x64-0.11.46.zip) from a dolthub/doltlite release. It contains doltlite.h and libdoltlite.a. mattn/go-sqlite3 built with the libsqlite3 tag includes <sqlite3.h>, so copy the header: cp doltlite.h sqlite3.h inside the unpacked directory.
2. Build from source: clone dolthub/doltlite at the pinned tag, then mkdir build && cd build && ../configure && make doltlite-lib (requires a C toolchain, tcl, and zlib headers, e.g. apt-get install build-essential tcl zlib1g-dev). The build directory generates sqlite3.h natively.

Then build the server, pointing cgo at the directory containing the header and static library:

CGO_CFLAGS="-I/path/to/doltlite/build" \
CGO_LDFLAGS="/path/to/doltlite/build/libdoltlite.a -lz -lpthread" \
go build -tags "doltlite libsqlite3" -o dolt-mcp-server-doltlite ./mcp/cmd/dolt-mcp-server

On Linux, append -lm -ldl to CGO_LDFLAGS. The static link means the resulting binary has no runtime dependency on a doltlite shared library.

Tools Unavailable in DoltLite Mode

DoltLite embeds a single database in a single file, so server- and multi-database-oriented tools are automatically hidden from clients in this mode:

• list_databases, create_database, drop_database, clone_database
• show_processlist, kill_process

Everything else (39 tools) works, including the dolt_tests tools, merge status, and remote operations against file:// URLs and DoltLite-compatible HTTP(S) remotes. Authenticated remotes use DoltLite credentials; create one through the exec tool with SELECT dolt_creds_new();, then configure the returned key with the remote service. The engine reads credentials from ~/.doltlite/creds by default or DOLTLITE_CREDS_DIR when set.

Behavioral Notes

• One database per file: the working_database tool argument is accepted but ignored; there is only ever one database.
• Commit author: configure --commit-name/--commit-email or commits are authored as "doltlite".
• Branch switching: dirty working sets are preserved independently per branch; switching away and back restores that branch's unstaged and staged state.
• Concurrency: each tool call uses its own pinned DoltLite database handle so branch and transaction state cannot leak between concurrent MCP operations. DoltLite coordinates those handles—and other applications opening the same file—with concurrent readers and one durable writer at a time. Configure lock waiting with --doltlite-busy-timeout.
• Remote compatibility: remote storage must speak DoltLite's file or HTTP(S) protocol; a full Dolt repository and a DoltLite database use different storage formats.

Configuration Options

Required Parameters

• --host: Hostname of the Dolt or DoltgreSQL server (not used with --doltlite)
• --user: Username for server authentication (not used with --doltlite)
• --stdio or --http: Server mode selection

Dialect Selection

• --dolt: Use the Dolt (MySQL-compatible) dialect. This is the default when no dialect flag is passed.
• --doltgres: Use the DoltgreSQL (PostgreSQL-compatible) dialect.
• --doltlite: Use the embedded DoltLite dialect. Requires --db-file and a binary built with DoltLite support (see DoltLite Mode).

--dolt, --doltgres, and --doltlite are mutually exclusive.

Optional Parameters

• --database: Name of the database to connect to
• --port: Server port. Defaults to 3306 for Dolt and 5432 for DoltgreSQL.
• --password: Password for authentication (can also use environment variable)
• --tls: TLS mode for the database connection: true, false, skip-verify, or preferred
• --tls-ca: Path to a CA certificate file for the database TLS connection
• --mcp-port: HTTP server port (default: 8080, HTTP mode only)
• --db-file: Path to the DoltLite database file, created if missing (required with --doltlite)
• --commit-name: Author name for Dolt commits (--doltlite only, recommended)
• --commit-email: Author email for Dolt commits (--doltlite only, recommended)
• --doltlite-busy-timeout: How long DoltLite waits for a conflicting lock (default 5s; 0 disables waiting)

Environment Variables

• DOLT_PASSWORD: Set the password for Dolt server authentication

Docker Environment Variables

When using Docker, you can configure the server using environment variables:

Required

• DOLT_HOST: Hostname of the Dolt SQL server (not used with doltlite)
• DOLT_USER: Username for Dolt server authentication (not used with doltlite)

Optional

• DOLT_DATABASE: Name of the database to connect to
• DOLT_PASSWORD: Password for authentication
• DOLT_PORT: Server port (default: 3306 for dolt, 5432 for doltgres)
• MCP_DIALECT: SQL dialect: dolt (MySQL-compatible), doltgres (PostgreSQL-compatible), or doltlite (embedded, requires the -doltlite image variant). Default: dolt (doltlite in the -doltlite images)
• MCP_MODE: Server mode: http or stdio (default: stdio)
• MCP_PORT: HTTP server port (default: 8080, HTTP mode only)

DoltLite Only (dolthub/dolt-mcp:<version>-doltlite images)

• DOLT_DB_FILE: Path to the DoltLite database file inside the container (default: /data/doltlite.db); mount a volume at /data to persist it
• DOLT_COMMIT_NAME: Author name for Dolt commits (recommended)
• DOLT_COMMIT_EMAIL: Author email for Dolt commits (recommended)
• DOLTLITE_BUSY_TIMEOUT: How long DoltLite waits for a conflicting lock (default: 5s; 0 disables waiting)
• DOLTLITE_CREDS_DIR: Credential directory for authenticated HTTP(S) remotes (default: /data/creds)
• DOLTLITE_CREDS_KID: Optional credential key ID when more than one key is present
• DOLTLITE_CA_FILE: Optional CA bundle for a private HTTPS remote

Docker Compose Example

version: '3.8'

services:
  dolt-mcp-server:
    image: dolthub/dolt-mcp:latest
    ports:
      - "8080:8080"
    environment:
      - MCP_MODE=http
      - DOLT_HOST=dolt-server
      - DOLT_PORT=3306
      - DOLT_USER=root
      - DOLT_DATABASE=myapp
      - DOLT_PASSWORD=secret
    depends_on:
      - dolt-server
    restart: unless-stopped

  dolt-server:
    image: dolthub/dolt-sql-server:latest
    ports:
      - "3306:3306"
    volumes:
      - dolt_data:/var/lib/dolt
    environment:
      - DOLT_ROOT_PATH=/var/lib/dolt
    restart: unless-stopped

volumes:
  dolt_data:

Available Tools

The Dolt MCP Server provides 40+ tools organized by functionality:

Database Management

• list_databases: List all available databases
• create_database: Create a new database
• drop_database: Remove a database
• select_version: Get Dolt server version information

Table Operations

• show_tables: List tables in current database
• show_create_table: Show table creation SQL
• describe_table: Show table schema and structure
• create_table: Create new tables
• alter_table: Modify table structure
• drop_table: Remove tables

Data Operations

• query: Execute SELECT queries (read operations)
• exec: Execute INSERT, UPDATE, DELETE queries (write operations)

Branch Management

• list_dolt_branches: List all branches
• select_active_branch: Show currently active branch
• create_dolt_branch: Create new branches
• create_dolt_branch_from_head: Create branch from current HEAD
• delete_dolt_branch: Remove branches
• move_dolt_branch: Rename branches

Version Control

• list_dolt_commits: View commit history
• create_dolt_commit: Create commits with staged changes
• stage_table_for_dolt_commit: Stage specific tables
• stage_all_tables_for_dolt_commit: Stage all modified tables
• unstage_table: Remove tables from staging area
• unstage_all_tables: Clear staging area

Diff and Status

• list_dolt_diff_changes_in_working_set: Show uncommitted changes
• list_dolt_diff_changes_by_table_name: Show changes for specific table
• list_dolt_diff_changes_in_date_range: Show changes within date range
• get_dolt_merge_status: Check merge conflicts and status

Merge Operations

• merge_dolt_branch: Merge branches (fast-forward when possible)
• merge_dolt_branch_no_fast_forward: Force merge commit

Reset Operations

• dolt_reset_soft: Soft reset to a revision (table, branch, commit, working set, or '.')
• dolt_reset_hard: Hard reset to a revision

Remote Operations

• list_dolt_remotes: List configured remotes
• add_dolt_remote: Add new remote repositories
• remove_dolt_remote: Remove remote repositories
• clone_database: Clone remote databases
• dolt_fetch_branch: Fetch specific branch from remote
• dolt_fetch_all_branches: Fetch all branches from remote
• dolt_push_branch: Push branch to remote
• dolt_pull_branch: Pull branch from remote

Example Workflows

Basic Database Operations

# Start the MCP server
./dolt-mcp-server --stdio --dolt --host localhost --user root --database testdb

# Example AI interactions:
# "Show me all tables in the database"
# "Create a table called users with id, name, and email columns"  
# "Insert some sample data into the users table"
# "Show me the current branch and recent commits"

Version Control Workflow

# Example AI workflow:
# "Create a new branch called 'feature-users'"
# "Switch to the feature-users branch" 
# "Create a users table with appropriate schema"
# "Stage and commit these changes"
# "Switch back to main and merge the feature branch"

Data Analysis

# Example AI interactions:
# "Show me all data in the sales table"
# "Calculate total revenue by month from the orders table"
# "Show me what changed in the products table in the last week"
# "Create a branch to experiment with data transformations"

Development

Running Tests

go test ./...

Integration Tests

The repository includes comprehensive integration tests that validate tool functionality against a real Dolt server instance.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

License

This project follows the same license as the main Dolt project.

Support

For issues and questions:

• Create issues in this repository
• Join the Dolt Discord community
• Check the Dolt documentation