
db-mcp
io.github.arthurhoch/db-mcp
Native SQL, schema metadata and query plans for Oracle, PostgreSQL, MySQL, SQLite and SQL Server.
Documentation
DB MCP
An MCP server in Rust for querying and modifying data in Oracle, PostgreSQL, MySQL and SQLite, and for querying Microsoft SQL Server. Each connection has a TOML file with its description, credentials and permissions. The agent selects a database by ID and executes SQL in its native dialect.
Download and run
Download a package from Releases. Rust and Oracle Instant Client are not required. Packages include the executable, a SQLite demo and configuration examples.
MCPB-compatible clients can install a .mcpb asset from the same release. Choose
the bundle matching your system and processor, then select your existing global
TOML file when the client asks. Connections and access modes use that configuration.
| System | x64 (Intel/AMD) | ARM64 (Apple Silicon/ARM) |
|---|---|---|
| macOS | Download | Download |
| Linux | Download | Download |
| Windows | Download | Download |
For example, on a Mac with Apple Silicon:
curl -fLO https://github.com/arthurhoch/db-mcp/releases/latest/download/db-mcp-macos-arm64.tar.gz
tar -xzf db-mcp-macos-arm64.tar.gz
cd db-mcp-macos-arm64
./db-mcp --version
./db-mcp --config demo/config/global.toml --check-config
On Windows, extract the ZIP and use db-mcp.exe. Configuration validation opens
no database. To query the demo, connect your MCP client to this executable with
--config pointing to the demo's global TOML, then ask it to list pending orders
in demo-ro.
Each release includes SHA256SUMS and GitHub build provenance. See
releases and verification for verification and publishing.
Build and test
Install Rust through rustup. The toolchain version is pinned in rust-toolchain.toml.
cargo build --release --locked
cargo fmt --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --all-targets --locked
The executable is built at target/release/db-mcp or target\release\db-mcp.exe.
Oracle uses oracledb, a Rust driver
that connects directly without installing Instant Client or Oracle libraries.
Try it with SQLite
cargo run --locked --example create_demo
target/release/db-mcp --config .runtime/demo/config/global.toml --check-config
target/release/db-mcp --config .runtime/demo/config/global.toml --test-connection demo-ro
Downloaded packages already include the demo. The Rust example creates sample
orders and three connections: demo-ro, demo-rw
and demo-ddl. It refuses to overwrite an existing directory. To use a different
destination, pass its path after --example create_demo --.
Connect to an agent
GitHub Copilot in VS Code
Follow the Copilot setup guide for a .vscode/mcp.json
example, server startup and a demo query. VS Code manages the executable as a
STDIO subprocess; no separate daemon is required.
Codex
Example for a client using the Codex TOML configuration format:
[mcp_servers.db_mcp]
command = "/absolute/path/db-mcp-macos-arm64/db-mcp"
args = ["--config", "/absolute/path/db-mcp-macos-arm64/demo/config/global.toml"]
Adjust the executable and configuration paths for your download or source build. The transport is STDIO. The process uses the catalog from the global configuration file, with no separate MCP login. Credential environment variables must be available to the process. Other MCP clients have their own configuration formats.
Example request: “In demo-ro, list the pending orders.” The agent uses
list_databases to find the connection, describe_database to inspect tables,
columns, indexes or constraints, and execute_sql to run SQL. explain_query
returns an estimated plan without running the query.
| Connection mode | Operations |
|---|---|
read_only | Read queries. |
read_write | Read queries, INSERT, UPDATE and DELETE. |
read_write_ddl | Also supported CREATE, ALTER and DROP statements. |
SQL Server supports read_only with verified TLS. See the
SQL Server configuration example.
Batches use one transaction per call. DDL statements run individually. The server reports truncated results and unknown effects; it does not retry SQL automatically.
For RLS/VPD, put context setup and dependent queries in the same statements batch.
Oracle supports packaged CALL; PostgreSQL supports SET LOCAL and custom
set_config(..., true). Statements run in order on the same connection. Oracle
packages that commit internally prevent a guaranteed rollback of the whole batch.
Configuration · MCP contract · Databases · Architecture · Testing · Skills · Privacy policy
https://github.com/arthurhoch/db-mcp/releases/download/v0.2.4/db-mcp-linux-x64.mcpb# mcpb: https://github.com/arthurhoch/db-mcp/releases/download/v0.2.4/db-mcp-linux-x64.mcpbhttps://github.com/arthurhoch/db-mcp/releases/download/v0.2.4/db-mcp-linux-arm64.mcpb# mcpb: https://github.com/arthurhoch/db-mcp/releases/download/v0.2.4/db-mcp-linux-arm64.mcpbhttps://github.com/arthurhoch/db-mcp/releases/download/v0.2.4/db-mcp-macos-x64.mcpb# mcpb: https://github.com/arthurhoch/db-mcp/releases/download/v0.2.4/db-mcp-macos-x64.mcpbhttps://github.com/arthurhoch/db-mcp/releases/download/v0.2.4/db-mcp-macos-arm64.mcpb# mcpb: https://github.com/arthurhoch/db-mcp/releases/download/v0.2.4/db-mcp-macos-arm64.mcpbhttps://github.com/arthurhoch/db-mcp/releases/download/v0.2.4/db-mcp-windows-x64.mcpb# mcpb: https://github.com/arthurhoch/db-mcp/releases/download/v0.2.4/db-mcp-windows-x64.mcpbhttps://github.com/arthurhoch/db-mcp/releases/download/v0.2.4/db-mcp-windows-arm64.mcpb# mcpb: https://github.com/arthurhoch/db-mcp/releases/download/v0.2.4/db-mcp-windows-arm64.mcpb