Dolt Mcp

Dolt MCP 服务

一个 Model Context Protocol（MCP）服务，可让 AI 助手直接访问 Dolt 和 DoltgreSQL 数据库。此服务使 Claude 等 AI 工具能够通过 MySQL 或 PostgreSQL 线协议与 Dolt 的版本控制 SQL 数据库交互，从而执行数据库操作、版本控制工作流和数据管理任务。

概述

Dolt MCP 服务充当 AI 助手与 Dolt 数据库之间的桥梁，提供一套全面的工具，用于：

• 数据库管理：创建、删除和管理数据库
• 表操作：创建、修改、删除、描述和查询表
• 版本控制：分支管理、提交、合并和差异比较
• 数据操作：插入、更新、删除和查询数据
• 远程操作：从远程仓库克隆、获取、推送和拉取

同时支持 Dolt（兼容 MySQL）和 DoltgreSQL（兼容 PostgreSQL）后端。SQL 方言通过启动时的 --dolt 或 --doltgres 标志选择。特别构建的二进制文件还提供嵌入式 DoltLite 后端（--doltlite），可直接使用本地数据库文件运行，无需服务端——请参阅 DoltLite 模式（嵌入式）。

安装

前置条件

• Go 1.25 或更高版本
• 正在运行的 Dolt 或 DoltgreSQL SQL 服务实例（DoltLite 模式无需此项）

从源代码构建

默认构建为纯 Go（不使用 cgo），可自由进行交叉编译：

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

以此方式构建的二进制文件不包含 DoltLite 支持（使用 --doltlite 会返回错误）。构建支持嵌入式 DoltLite 的版本需要 cgo 和 libdoltlite；请参阅构建支持 DoltLite 的版本。

Docker 安装

拉取官方 Docker 镜像：

docker pull dolthub/dolt-mcp:latest

使用方法

Dolt MCP 服务可以通过两种模式运行，并支持多种部署方式：

Docker 使用方法（推荐用于生产环境）

使用 Docker 运行 HTTP 服务

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

使用 Docker 运行 Stdio 服务

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

从 Docker 连接到 DoltgreSQL

设置 MCP_DIALECT=doltgres，让容器连接到 DoltgreSQL 服务。方言为 doltgres 时，DOLT_PORT 默认值为 5432。

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

原生二进制文件使用方法

1. Stdio 服务（推荐用于 AI 助手）

Stdio 服务通过标准输入/输出进行通信，非常适合与 Claude Desktop 等 AI 助手集成。

连接到 Dolt（MySQL 方言，默认）：

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

连接到 DoltgreSQL（PostgreSQL 方言）：

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

如果省略 --port，Dolt 的默认端口为 3306，DoltgreSQL 的默认端口为 5432。

Claude Desktop 配置

将以下配置添加到 Claude Desktop 的 MCP 设置中：

{
  "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"
      }
    }
  }
}

对于 DoltgreSQL 后端，请将 --dolt 替换为 --doltgres，并调整端口和用户以匹配你的服务。

HTTP 客户端配置

连接到以 HTTP 模式运行的 Dolt MCP 服务时，可以将 Claude 配置为使用 HTTP 传输。重要提示：HTTP 连接需要在服务 URL 后添加 /mcp 端点。

使用 Claude CLI

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

Claude Desktop 配置

将以下配置添加到 Claude Desktop 的 MCP 设置中：

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

注意：请将 your-dolt-host、端口和 <your-token> 替换为实际的服务信息。HTTP 连接必须使用 /mcp 端点。

2. HTTP 服务

HTTP 服务提供用于 MCP 工具调用的 REST API，适用于 Web 应用和自定义集成。

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

连接到 DoltgreSQL 服务时，请用 --doltgres 替换 --dolt。

DoltLite 模式（嵌入式）

DoltLite 是 SQLite 的一个分支，增加了 Dolt 的版本控制功能：一个完整的版本控制数据库——包括分支、提交、差异、合并和远程库——都存储在单个本地文件中。在 DoltLite 模式下，MCP 服务会直接嵌入数据库引擎，因此无需安装、配置或运行 Dolt 或 DoltgreSQL 服务：只需将服务指向一个数据库文件（如果文件不存在，会在首次使用时创建），即可开始使用。这非常适合在笔记本电脑或容器中运行本地优先的 AI 工作流。

DoltLite 模式需要使用启用了 DoltLite 支持的二进制文件。Linux 和 macOS（amd64/arm64）以及 Windows x64 的预构建归档文件 dolt-mcp-server-doltlite-<platform> 附在发行版中，多架构 Docker 镜像 dolthub/dolt-mcp:<version>-doltlite 也包含该支持。默认的纯 Go 构建不包含此支持：向其传入 --doltlite 会报错：this binary was built without DoltLite support; rebuild with -tags "doltlite libsqlite3" ...。

使用 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 [email protected] \
  dolthub/dolt-mcp:latest-doltlite

在 /data 挂载一个卷，以便数据库文件在容器重启后仍能保留。完整的环境变量列表请参阅 docker/README.md。

使用原生二进制文件快速开始

从发行版页面下载 dolt-mcp-server-doltlite 归档文件（或按下文说明自行构建），然后：

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

无需使用 --host、--port、--user、--password 或 TLS 标志 — DoltLite 会在进程内直接操作文件。

DoltLite 标志

• --doltlite：使用嵌入式 DoltLite 方言。不能与 --dolt 和 --doltgres 同时使用。
• --db-file：DoltLite 数据库文件的路径（与 --doltlite 一起使用时必需）。如果文件不存在，则会创建。
• --commit-name / --commit-email：Dolt 提交使用的作者姓名和电子邮箱。建议设置 — 若未设置，提交的作者会默认为 "doltlite"。
• --doltlite-busy-timeout：DoltLite 等待冲突锁的时长（默认值为 5s；0 表示不等待）。

Claude Desktop 配置（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", "[email protected]"
      ]
    }
  }
}

构建支持 DoltLite 的版本

DoltLite 支持需要 cgo、doltlite 和 libsqlite3 构建标签，以及 libdoltlite（含 zlib 和 pthreads）。由于使用了 cgo，DoltLite 二进制文件无法交叉编译 — 请在目标平台上构建。

可以通过以下任一方式获取 libdoltlite：

1. GitHub 发行版 zip 文件：从 dolthub/doltlite 发行版下载 doltlite-lib-<platform>-<version>.zip 资源文件（例如 doltlite-lib-linux-x64-0.11.46.zip）。其中包含 doltlite.h 和 libdoltlite.a。使用 libsqlite3 标签构建的 mattn/go-sqlite3 包含 <sqlite3.h>，因此请在解压后的目录中复制头文件：cp doltlite.h sqlite3.h。
2. 从源代码构建：在固定的标签版本上克隆 dolthub/doltlite，然后运行 mkdir build && cd build && ../configure && make doltlite-lib（需要 C 工具链、tcl 和 zlib 头文件，例如运行 apt-get install build-essential tcl zlib1g-dev）。构建目录会原生生成 sqlite3.h。

然后构建服务，并将 cgo 指向包含头文件和静态库的目录：

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

在 Linux 上，将 -lm -ldl 附加到 CGO_LDFLAGS。由于采用静态链接，生成的二进制文件在运行时无需依赖 doltlite 共享库。

DoltLite 模式下不可用的工具

DoltLite 会将单个数据库嵌入单个文件，因此在此模式下，面向服务器和多数据库的工具会自动对客户端隐藏：

• list_databases、create_database、drop_database、clone_database
• show_processlist、kill_process

其他所有工具（39 个）均可使用，包括 dolt_tests 工具、合并状态，以及针对 file:// URL 和兼容 DoltLite 的 HTTP(S) 远程服务执行的远程操作。经过身份验证的远程服务使用 DoltLite 凭据；通过 exec 工具执行 SELECT dolt_creds_new(); 创建凭据，然后在远程服务中配置返回的密钥。引擎默认从 ~/.doltlite/creds 读取凭据；如果设置了 DOLTLITE_CREDS_DIR，则从该目录读取。

行为说明

• 每个文件对应一个数据库：系统会接受 working_database 工具参数，但会忽略它；始终只有一个数据库。
• 提交作者：配置 --commit-name/--commit-email，否则提交的作者会显示为 "doltlite"。
• 分支切换：每个分支会独立保留未提交的工作集；切换到其他分支后再切回，会恢复该分支暂存和未暂存的状态。
• 并发：每次工具调用都会使用各自固定的 DoltLite 数据库句柄，因此分支和事务状态不会在并发 MCP 操作之间泄漏。DoltLite 会协调这些句柄以及其他打开同一文件的应用，使并发读取者可以同时访问，但同一时间只有一个持久化写入者。使用 --doltlite-busy-timeout 配置锁等待。
• 远程兼容性：远程存储必须使用 DoltLite 的文件或 HTTP(S) 协议；完整的 Dolt 仓库与 DoltLite 数据库使用不同的存储格式。

配置选项

必需参数

• --host：Dolt 或 DoltgreSQL 服务器的主机名（与 --doltlite 一起使用时不适用）
• --user：服务器身份验证的用户名（与 --doltlite 一起使用时不适用）
• --stdio 或 --http：服务器模式选择

方言选择

• --dolt：使用 Dolt（兼容 MySQL）方言。未传入方言标志时，这是默认选项。
• --doltgres：使用 DoltgreSQL（兼容 PostgreSQL）方言。
• --doltlite：使用嵌入式 DoltLite 方言。需要 --db-file 和支持 DoltLite 的二进制文件（参见 DoltLite 模式）。

--dolt、--doltgres 和 --doltlite 互斥。

可选参数

• --database：要连接的数据库名称
• --port：服务器端口。Dolt 默认为 3306，DoltgreSQL 默认为 5432。
• --password：身份验证密码（也可以使用环境变量）
• --tls：数据库连接的 TLS 模式：true、false、skip-verify 或 preferred
• --tls-ca：数据库 TLS 连接的 CA 证书文件路径
• --mcp-port：HTTP 服务器端口（默认值：8080，仅限 HTTP 模式）
• --db-file：DoltLite 数据库文件的路径；如果文件不存在则会创建（与 --doltlite 一起使用时必需）
• --commit-name：Dolt 提交的作者姓名（仅限 --doltlite，建议设置）
• --commit-email：Dolt 提交的作者邮箱（仅限 --doltlite，建议设置）
• --doltlite-busy-timeout：DoltLite 等待冲突锁的时长（默认值为 5s；0 表示不等待）

环境变量

• DOLT_PASSWORD：设置 Dolt 服务器身份验证密码

Docker 环境变量

使用 Docker 时，可以通过环境变量配置服务器：

必需

• DOLT_HOST：Dolt SQL 服务器的主机名（与 doltlite 一起使用时不适用）
• DOLT_USER：Dolt 服务器身份验证的用户名（与 doltlite 一起使用时不适用）

可选

• DOLT_DATABASE：要连接的数据库名称
• DOLT_PASSWORD：用于身份验证的密码
• DOLT_PORT：服务端口（默认值：dolt 为 3306，doltgres 为 5432）
• MCP_DIALECT：SQL 方言：dolt（兼容 MySQL）、doltgres（兼容 PostgreSQL）或 doltlite（嵌入式，需使用 -doltlite 镜像变体）。默认值：dolt（-doltlite 镜像中为 doltlite）
• MCP_MODE：服务模式：http 或 stdio（默认值：stdio）
• MCP_PORT：HTTP 服务端口（默认值：8080，仅限 HTTP 模式）

仅适用于 DoltLite（dolthub/dolt-mcp:<version>-doltlite 镜像）

• DOLT_DB_FILE：容器内 DoltLite 数据库文件的路径（默认值：/data/doltlite.db）；在 /data 挂载卷以持久化数据
• DOLT_COMMIT_NAME：Dolt 提交的作者姓名（建议设置）
• DOLT_COMMIT_EMAIL：Dolt 提交的作者邮箱（建议设置）
• DOLTLITE_BUSY_TIMEOUT：DoltLite 等待冲突锁的时长（默认值：5s；0 表示不等待）
• DOLTLITE_CREDS_DIR：用于经过身份验证的 HTTP(S) 远程服务的凭据目录（默认值：/data/creds）
• DOLTLITE_CREDS_KID：存在多个密钥时可选的凭据密钥 ID
• DOLTLITE_CA_FILE：私有 HTTPS 远程服务可选的 CA 证书包

Docker Compose 示例

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:

可用工具

Dolt MCP Server 提供 40 多种工具，按功能分类：

数据库管理

• list_databases：列出所有可用数据库
• create_database：创建新数据库
• drop_database：删除数据库
• select_version：获取 Dolt 服务版本信息

表操作

• show_tables：列出当前数据库中的表
• show_create_table：显示建表 SQL
• describe_table：显示表的架构和结构
• create_table：创建新表
• alter_table：修改表结构
• drop_table：删除表

数据操作

• query：执行 SELECT 查询（读取操作）
• exec：执行 INSERT、UPDATE、DELETE 查询（写入操作）

分支管理

• list_dolt_branches：列出所有分支
• select_active_branch：显示当前活动分支
• create_dolt_branch：创建新分支
• create_dolt_branch_from_head：从当前 HEAD 创建分支
• delete_dolt_branch：删除分支
• move_dolt_branch：重命名分支

版本控制

• list_dolt_commits：查看提交历史
• create_dolt_commit：将暂存的更改创建为提交
• stage_table_for_dolt_commit：暂存指定表
• stage_all_tables_for_dolt_commit：暂存所有已修改的表
• unstage_table：从暂存区移除表
• unstage_all_tables：清空暂存区

差异和状态

• list_dolt_diff_changes_in_working_set：显示未提交的更改
• list_dolt_diff_changes_by_table_name：显示指定表的更改
• list_dolt_diff_changes_in_date_range：显示指定日期范围内的更改
• get_dolt_merge_status：检查合并冲突和状态

合并操作

• merge_dolt_branch：合并分支（可能时执行快进合并）
• merge_dolt_branch_no_fast_forward：强制创建合并提交

重置操作

• dolt_reset_soft：软重置到某个修订版本（表、分支、提交、工作集或“.”）
• dolt_reset_hard：硬重置到某个修订版本

远程操作

• list_dolt_remotes：列出已配置的远程服务
• add_dolt_remote：添加远程仓库
• remove_dolt_remote：移除远程仓库
• clone_database：克隆远程数据库
• dolt_fetch_branch：从远程服务获取指定分支
• dolt_fetch_all_branches：从远程服务获取所有分支
• dolt_push_branch：将分支推送到远程服务
• dolt_pull_branch：从远程服务拉取分支

示例工作流

基本数据库操作

# 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"

版本控制工作流

# 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"

数据分析

# 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"

开发

运行测试

go test ./...

集成测试

此仓库包含全面的集成测试，用于验证工具在真实 Dolt 服务实例上的功能。

贡献

1. Fork 此代码库
2. 创建功能分支
3. 进行更改
4. 为新功能添加测试
5. 提交拉取请求

许可证

本项目采用与 Dolt 主项目相同的许可证。

支持

如有问题或疑问：

• 在此代码库中创建问题
• 加入 Dolt Discord 社区
• 查看 Dolt 文档