db-mcp

MCP server that gives LLM agents read access to any database, with built-in gates for writes.

Why db-mcp

LLMs handle read-only database work: schema exploration, query writing, data analysis. A stray DELETE or DROP from an agent can wipe production data. db-mcp draws a hard line: reads go through, writes require the agent to show you exactly what it plans to do and wait for your explicit approval.

Features

• Read queries run immediately: SELECT, EXPLAIN, SHOW, DESCRIBE, and WITH (when safe).
• Write and destructive queries go through a two-step confirmation: the agent previews the change, you approve it.
• Token-bound execution. Approval tokens encode the exact SQL and connection. Swap the query or target a different database, and the server rejects it.
• Named connections via DB_<NAME>=<url> environment variables. No config files to manage.
• Any SQLAlchemy-compatible database: PostgreSQL, SQLite, Oracle, MySQL, SQL Server, Snowflake, or whatever you install the driver for.

Supported databases

Any other database works too. Install the right SQLAlchemy driver and use its URL format.

Quick start

# Clone the repo
git clone [email protected]:paulushcgcj/db-mcp.git
cd db-mcp

# Run with a local SQLite database
DB_LOCAL=sqlite:///./test.db ./run.sh

The server starts and your LLM tool can list tables, describe schemas, and run read queries against local.

Configure your connections

Set DB_<NAME>=<url> environment variables. The part after DB_ (lowercased) is the name you reference in prompts.

DB_PROD=postgresql://user:[email protected]:5432/production
DB_LOCAL=sqlite:///./dev.db
DB_MAX_ROWS=1000   # optional, default 500

Put these in a .env file if you run the server manually.

Run the server

run.sh is the recommended launcher. It syncs dependencies, detects which database drivers your DB_* env vars need, installs them if missing, and hands off to the MCP server.

# Run manually
DB_LOCAL=sqlite:///./test.db ./run.sh

# Or with a .env file
./run.sh

When your IDE launches db-mcp, point it at run.sh instead of calling uv run db-mcp directly. The script handles driver installation so you don't have to pip install extras like [oracle] or [mysql] by hand.

Connect your IDE

<details> <summary><strong>VS Code Copilot</strong></summary>

Add to .vscode/mcp.json (workspace) or ~/.vscode/mcp.json (global):

{
  "servers": {
    "db-mcp": {
      "type": "stdio",
      "command": "/absolute/path/to/db-mcp/run.sh",
      "env": {
        "DB_PROD": "postgresql://user:pass@host:5432/mydb",
        "DB_LOCAL": "sqlite:///./local.db",
        "DB_MAX_ROWS": "500"
      }
    }
  }
}

</details>

<details> <summary><strong>OpenCode</strong></summary>

Add to ~/.config/opencode/opencode.jsonc or .opencode.json in your project:

{
  "mcp": {
    "db-mcp": {
      "type": "local",
      "command": ["/absolute/path/to/db-mcp/run.sh"],
      "environment": {
        "DB_PROD": "postgresql://user:pass@host:5432/mydb",
        "DB_LOCAL": "sqlite:///./local.db",
        "DB_MAX_ROWS": "500"
      }
    }
  }
}

</details>

Tools

How writes get approved

Every write or destructive query follows the same flow:

Agent calls preview_mutation(connection, sql)
  → Server returns a preview of the change + a one-time token (5-minute TTL)

Agent shows you the preview:
  "This will DELETE 42 rows from orders. Do you confirm?"

You say yes.

Agent calls execute_mutation(connection, sql, token)
  → Server validates the token, executes, and consumes it.

The token binds the connection name and the exact SQL to the approval. If the agent tries to run different SQL or target a different connection, the server rejects the token. Tokens expire after 5 minutes and can only be used once.

Custom drivers

run.sh detects the URL scheme and installs the driver for you. For example, setting DB_SNOW=snowflake://... causes the script to install snowflake-sqlalchemy on first launch.

If you prefer to install manually:

uv pip install snowflake-sqlalchemy

The SQLAlchemy dialect registry resolves the driver from the URL prefix.

Environment reference

Contributing

See CONTRIBUTING.md for development setup, code style, and PR guidelines.

License

GPL-3.0