Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 34 additions & 2 deletions .github/workflows/integration_tests.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ concurrency:
cancel-in-progress: true

jobs:
test:
name: Integration Tests
test-dolt:
name: Integration Tests (Dolt / MySQL)
runs-on: ubuntu-22.04
defaults:
run:
Expand All @@ -36,3 +36,35 @@ jobs:
run: |
go test -timeout 30m ./...

test-doltgres:
name: Integration Tests (DoltgreSQL / PostgreSQL)
runs-on: ubuntu-22.04
defaults:
run:
shell: bash
steps:
- uses: actions/checkout@v4
- name: Set up Go 1.x
uses: actions/setup-go@v5
with:
go-version-file: ./go.mod
id: go
- name: Install latest DoltgreSQL
run: |
set -euo pipefail
ASSET_URL=$(curl -sL https://api.github.com/repos/dolthub/doltgresql/releases/latest \
| grep "browser_download_url.*linux-amd64" \
| head -n1 \
| cut -d '"' -f 4)
echo "Downloading: $ASSET_URL"
curl -L -o /tmp/doltgres.tar.gz "$ASSET_URL"
mkdir -p /tmp/doltgres-extract
tar -xzf /tmp/doltgres.tar.gz -C /tmp/doltgres-extract
sudo mv /tmp/doltgres-extract/*/bin/doltgres /usr/local/bin/doltgres
doltgres --version || true
- name: Test All
working-directory: ./mcp/integration_tests/
env:
DOLT_DIALECT: postgres
run: |
go test -timeout 30m ./...
94 changes: 73 additions & 21 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Dolt MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with direct access to Dolt databases. This server enables AI tools like Claude to interact with Dolt's version-controlled SQL databases, allowing for database operations, version control workflows, and data management tasks.
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

Expand All @@ -12,12 +12,14 @@ The Dolt MCP Server acts as a bridge between AI assistants and Dolt databases, e
- **Data Operations**: Insert, update, delete, and query data
- **Remote Operations**: Clone, fetch, push, and pull from remote repositories

Both [Dolt](https://github.com/dolthub/dolt) (MySQL-compatible) and [DoltgreSQL](https://github.com/dolthub/doltgresql) (PostgreSQL-compatible) backends are supported. The SQL dialect is selected at startup with the `--dolt` or `--doltgres` flag.

## Installation

### Prerequisites

- Go 1.24.4 or later
- A running Dolt SQL server instance
- A running Dolt or DoltgreSQL SQL server instance

### Building from Source

Expand Down Expand Up @@ -67,21 +69,55 @@ docker run -it --rm \
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`.

```bash
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):

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

Against DoltgreSQL (PostgreSQL dialect):

```bash
./dolt-mcp-server \
--stdio \
--dolt-host 0.0.0.0 \
--dolt-port 3306 \
--dolt-user root \
--dolt-database mydb
--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:
Expand All @@ -93,10 +129,11 @@ Add this configuration to your Claude Desktop MCP settings:
"command": "/path/to/dolt-mcp-server",
"args": [
"--stdio",
"--dolt-host", "0.0.0.0",
"--dolt-port", "3306",
"--dolt-user", "root",
"--dolt-database", "your_database_name"
"--dolt",
"--host", "0.0.0.0",
"--port", "3306",
"--user", "root",
"--database", "your_database_name"
],
"env": {
"DOLT_PASSWORD": "your_password_if_needed"
Expand All @@ -106,6 +143,8 @@ Add this configuration to your Claude Desktop MCP settings:
}
```

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.
Expand Down Expand Up @@ -144,25 +183,37 @@ The HTTP server exposes a REST API for MCP tool calls, useful for web applicatio
./dolt-mcp-server \
--http \
--mcp-port 8080 \
--dolt-host 0.0.0.0 \
--dolt-port 3306 \
--dolt-user root \
--dolt-database mydb
--dolt \
--host 0.0.0.0 \
--port 3306 \
--user root \
--database mydb
```

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

## Configuration Options

### Required Parameters

- `--dolt-host`: Hostname of the Dolt SQL server
- `--dolt-user`: Username for Dolt server authentication
- `--host`: Hostname of the Dolt or DoltgreSQL server
- `--user`: Username for server authentication
- `--stdio` or `--http`: Server mode selection

### Dialect Selection

- `--dolt`: Use the Dolt (MySQL-compatible) dialect. This is the default when neither flag is passed.
- `--doltgres`: Use the DoltgreSQL (PostgreSQL-compatible) dialect.

`--dolt` and `--doltgres` are mutually exclusive.

### Optional Parameters

- `--dolt-database`: Name of the database to connect to
- `--dolt-port`: Dolt server port (default: 3306)
- `--dolt-password`: Password for authentication (can also use environment variable)
- `--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)

### Environment Variables
Expand All @@ -180,7 +231,8 @@ When using Docker, you can configure the server using environment variables:
#### Optional
- `DOLT_DATABASE`: Name of the database to connect to
- `DOLT_PASSWORD`: Password for authentication
- `DOLT_PORT`: Dolt server port (default: 3306)
- `DOLT_PORT`: Server port (default: 3306 for `dolt`, 5432 for `doltgres`)
- `MCP_DIALECT`: SQL dialect: `dolt` (MySQL-compatible) or `doltgres` (PostgreSQL-compatible). Default: `dolt`
- `MCP_MODE`: Server mode: `http` or `stdio` (default: stdio)
- `MCP_PORT`: HTTP server port (default: 8080, HTTP mode only)

Expand Down Expand Up @@ -287,7 +339,7 @@ The Dolt MCP Server provides 40+ tools organized by functionality:

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

# Example AI interactions:
# "Show me all tables in the database"
Expand Down
1 change: 0 additions & 1 deletion docker/Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,6 @@ HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \

# Set default environment variables
ENV DOLT_HOST=127.0.0.1
ENV DOLT_PORT=3306
ENV DOLT_USER=root
ENV DOLT_DATABASE=
ENV MCP_MODE=stdio
Expand Down
3 changes: 2 additions & 1 deletion docker/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,8 @@ docker run -it --rm \

### Optional
- `DOLT_PASSWORD` - Password for authentication (recommended to use Docker secrets in production)
- `DOLT_PORT` - Dolt server port (default: 3306)
- `DOLT_PORT` - Server port (default: 3306 for `dolt`, 5432 for `doltgres`)
- `MCP_DIALECT` - SQL dialect: `dolt` (MySQL-compatible) or `doltgres` (PostgreSQL-compatible). Default: `dolt`
- `MCP_MODE` - Server mode: `http` or `stdio` (default: stdio)
- `MCP_PORT` - HTTP server port (default: 8080, HTTP mode only)

Expand Down
32 changes: 27 additions & 5 deletions docker/entrypoint.sh
Original file line number Diff line number Diff line change
Expand Up @@ -21,19 +21,41 @@ if [ -z "$DOLT_USER" ]; then
exit 1
fi

# Determine SQL dialect (default: dolt)
MCP_DIALECT="${MCP_DIALECT:-dolt}"
case "$MCP_DIALECT" in
dolt)
CMD_ARGS="$CMD_ARGS --dolt"
DEFAULT_PORT=3306
;;
doltgres)
CMD_ARGS="$CMD_ARGS --doltgres"
DEFAULT_PORT=5432
;;
*)
echo "Error: MCP_DIALECT must be either 'dolt' or 'doltgres' (got: $MCP_DIALECT)"
exit 1
;;
esac

# Default port based on dialect if not explicitly provided
if [ -z "$DOLT_PORT" ]; then
DOLT_PORT="$DEFAULT_PORT"
fi

# Add required parameters
CMD_ARGS="$CMD_ARGS --dolt-host $DOLT_HOST"
CMD_ARGS="$CMD_ARGS --dolt-port $DOLT_PORT"
CMD_ARGS="$CMD_ARGS --dolt-user $DOLT_USER"
CMD_ARGS="$CMD_ARGS --host $DOLT_HOST"
CMD_ARGS="$CMD_ARGS --port $DOLT_PORT"
CMD_ARGS="$CMD_ARGS --user $DOLT_USER"

# Add password if provided
if [ -n "$DOLT_PASSWORD" ]; then
CMD_ARGS="$CMD_ARGS --dolt-password $DOLT_PASSWORD"
CMD_ARGS="$CMD_ARGS --password $DOLT_PASSWORD"
fi

# Add database if provided
if [ -n "$DOLT_DATABASE" ]; then
CMD_ARGS="$CMD_ARGS --dolt-database $DOLT_DATABASE"
CMD_ARGS="$CMD_ARGS --database $DOLT_DATABASE"
fi

# Determine server mode
Expand Down
21 changes: 15 additions & 6 deletions go.mod
Original file line number Diff line number Diff line change
@@ -1,15 +1,18 @@
module github.com/dolthub/dolt-mcp

go 1.25
go 1.25.0

require (
github.com/dolthub/dolt/go v0.40.5-0.20250717234857-c708eac7b968
github.com/dolthub/go-mysql-server v0.20.1-0.20250717202802-75c0b198280d
github.com/dolthub/vitess v0.0.0-20250611225316-90a5898bfe26
github.com/go-sql-driver/mysql v1.9.3
github.com/google/uuid v1.6.0
github.com/jackc/pgx/v5 v5.7.6
github.com/mark3labs/mcp-go v0.34.0
github.com/stretchr/testify v1.10.0
github.com/pganalyze/pg_query_go/v6 v6.2.2
github.com/stretchr/testify v1.11.1
github.com/wasilibs/go-pgquery v0.0.0-20260406132815-2d1882eb027f
go.uber.org/zap v1.27.0
golang.org/x/sync v0.16.0
google.golang.org/grpc v1.57.1
Expand All @@ -27,6 +30,9 @@ require (
github.com/golang/protobuf v1.5.3 // indirect
github.com/golang/snappy v0.0.4 // indirect
github.com/hashicorp/golang-lru v0.5.4 // indirect
github.com/jackc/pgpassfile v1.0.0 // indirect
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
github.com/jackc/puddle/v2 v2.2.2 // indirect
github.com/klauspost/cpuid/v2 v2.0.12 // indirect
github.com/lib/pq v1.10.0 // indirect
github.com/mohae/uvarint v0.0.0-20160208145430-c3f9e62bf2b0 // indirect
Expand All @@ -36,17 +42,20 @@ require (
github.com/silvasur/buzhash v0.0.0-20160816060738-9bdec3dec7c6 // indirect
github.com/sirupsen/logrus v1.8.1 // indirect
github.com/spf13/cast v1.7.1 // indirect
github.com/tetratelabs/wazero v1.11.0 // indirect
github.com/wasilibs/wazero-helpers v0.0.0-20250123031827-cd30c44769bb // indirect
github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
github.com/zeebo/xxh3 v1.0.2 // indirect
go.opentelemetry.io/otel v1.32.0 // indirect
go.opentelemetry.io/otel/metric v1.32.0 // indirect
go.opentelemetry.io/otel/trace v1.32.0 // indirect
go.uber.org/multierr v1.10.0 // indirect
golang.org/x/crypto v0.36.0 // indirect
golang.org/x/sys v0.31.0 // indirect
golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d // indirect
golang.org/x/crypto v0.37.0 // indirect
golang.org/x/sys v0.42.0 // indirect
golang.org/x/text v0.28.0 // indirect
golang.org/x/tools v0.36.0 // indirect
google.golang.org/genproto/googleapis/rpc v0.0.0-20230803162519-f966b187b2e5 // indirect
google.golang.org/protobuf v1.31.0 // indirect
google.golang.org/protobuf v1.36.11 // indirect
gopkg.in/go-jose/go-jose.v2 v2.6.3 // indirect
gopkg.in/src-d/go-errors.v1 v1.0.0 // indirect
gopkg.in/yaml.v3 v3.0.1 // indirect
Expand Down
Loading
Loading