Database MCP

@cocaxcode/database-mcp

Your databases, one conversation away.

33 tools · PostgreSQL · MySQL · SQLite · Connection Groups · Rollback · Dump/Restore · Schema auto-discovery

Overview · Just Talk to It · Connection Groups · Installation · Features · Tool Reference · Storage · Architecture

---

Quick Overview

The most complete MCP server for databases. 33 tools across 3 engines (PostgreSQL, MySQL, SQLite), with connection groups, named connection management, automatic rollback, dump/restore, schema auto-discovery via MCP Resources, and full query history — all from natural language.

This is not just a query runner. It is a full database workbench: organize connections into groups scoped to your project directories, set defaults that persist between sessions, introspect schemas at three levels of detail, get pre-mutation snapshots on every write, undo mistakes with reverse SQL, dump and restore entire databases, and track every query you run — per project, per connection.

Every connection belongs to a group. Groups have scopes (directories), a default connection, and an active connection. When you work inside a scoped directory, you only see that group's connections — no clutter, no confusion.

You describe what you need. The AI reads your schema, writes the SQL, and executes it safely — with automatic LIMIT injection, pre-mutation snapshots, and confirmation before destructive operations. No cloud accounts, no ORMs, no config files. Credentials never leave your machine. Everything runs locally.

Works with Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Codex CLI, Gemini CLI, and any MCP-compatible client.

---

Just Talk to It

You don't need to memorize tool names or SQL syntax. Just say what you want.

> "Connect to my local PostgreSQL on port 5432, database myapp, user admin"

"Create a group called backend and add this directory"

"Connect to my PostgreSQL on localhost, put it in the backend group"

"Set local-pg as the default connection"

"Show me all tables"

"What columns does the users table have?"

"Show me the last 10 orders with the customer name"

-> AI reads FKs from schema, builds the JOIN, applies LIMIT 10

"Insert a test user called Alice"

-> Snapshot captured for rollback

"Oops, undo that"

-> Rows restored via reverse SQL

"Switch to the production database for this session"

-> Instant context change, all queries now go to prod

"Delete all inactive users"

-> "This will affect N rows. Call again with confirm=true to proceed."

"What did I run today?"

-> Full query history with timestamps and execution times

"Dump the database — structure and data"

-> SQL file generated, ready for restore

The AI already knows your schema through MCP Resources. It reads db://schema to discover tables and db://tables/{name}/schema for columns, foreign keys, and indexes. When you ask for data across tables, it builds correct JOINs automatically.

---

Connection Groups

Every connection belongs to a group. Groups are the organizing unit for your database connections — they keep things scoped, clean, and automatic.

A group has three key concepts:

• Scopes: directories that share the group's connections. When you work inside a scoped directory, you only see that group's connections. No global clutter.
• Default: the connection that activates automatically when you enter a scoped directory. Persists between sessions.
• Active: the connection being used right now. Session only — resets to the default on restart.

Here is a practical workflow:

"Create a group called backend"

"Add this directory as scope" "Create a PostgreSQL connection called local-dev in the backend group" <- auto-default (first connection) "Create another called production in backend" "List connections" <- shows local-dev (active, default) "Switch to production" <- session only "Set production as default" <- persists between sessions

The first connection added to a group becomes the default automatically. Switching connections only changes the active for the current session — restart and you are back to the default. If you want the change to stick, set a new default explicitly.

This means you can safely switch to production for a quick query and know that next time you open the project, you will be back on your development database.

---

Installation

Claude Code

claude mcp add --scope user database -- npx -y @cocaxcode/database-mcp@latest

Claude Desktop

Add to your config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{

"mcpServers": { "database": { "command": "npx", "args": ["-y", "@cocaxcode/database-mcp@latest"] } } }

Cursor / Windsurf

Add to .cursor/mcp.json or .windsurf/mcp.json in your project root:

{

"mcpServers": { "database": { "command": "npx", "args": ["-y", "@cocaxcode/database-mcp@latest"] } } }

</details>

VS Code

Add to .vscode/mcp.json:

{

"servers": { "database": { "type": "stdio", "command": "npx", "args": ["-y", "@cocaxcode/database-mcp@latest"] } } }

</details>

Codex CLI (OpenAI)

codex mcp add database -- npx -y @cocaxcode/database-mcp@latest

Or add to ~/.codex/config.toml:

[mcp_servers.database]

command = "npx" args = ["-y", "@cocaxcode/database-mcp@latest"]

</details>

Gemini CLI (Google)

Add to ~/.gemini/settings.json:

{

"mcpServers": { "database": { "command": "npx", "args": ["-y", "@cocaxcode/database-mcp@latest"] } } }

</details>

Driver installation

Install only the driver(s) you need — they load dynamically at runtime:

npm install -g postgres       # PostgreSQL (postgres.js)

npm install -g mysql2 # MySQL npm install -g sql.js # SQLite (runs in-process, no native bindings)

Note: When using npx, drivers must be installed globally. If you install the server globally (npm install -g @cocaxcode/database-mcp), drivers can be local or global.

---

Features

Multi-database, one interface

Most database MCP servers make you reconfigure credentials every session. This one does not. Named connections persist inside groups — create them once, use them forever.

Named connections work like git branches. You create dev, staging, prod once inside a group and they are always there. Switching is instant — one command, zero reconfiguration:

"Create a group called my-project and add this directory as scope"

"Create a connection called dev with host localhost, database myapp, user admin in my-project" "Create a read-only connection called analytics pointing to ./data/metrics.db in my-project" "Switch to dev" -> queries go to PostgreSQL "Switch to analytics" -> queries go to SQLite "Duplicate dev as dev-readonly with read-only mode"

Group-scoped connections mean different projects see different databases automatically. Working on project A? You see project A's group and connections. Switch to project B's directory and it picks up project B's group with its own default. No manual switching, no interference between projects:

"Create a group called frontend with scope /home/user/frontend"

"Create a group called backend with scope /home/user/backend"

Now each directory has its own isolated set of connections.

100% local credentials. Every connection is stored as a JSON file in ~/.database-mcp/connections/. Passwords never leave your machine. Nothing is sent to the cloud. Nothing is committed to git. Your credentials are yours.

Live management. Create, duplicate, rename, test, export, and switch connections mid-conversation. No restart needed, no config file editing, no context loss.

Safety built in

Rollback snapshots

Every mutation captures a pre-state snapshot. Undo anything.

"Show me available rollbacks"

"Rollback the last delete" -> "This will INSERT 47 rows back into orders. Confirm?" -> Rows restored via reverse SQL

Schema introspection

Three levels of detail, with pattern filtering:

"List all tables"                         -> names only (fast)

"Show me the users table with columns" -> columns + types + nullable "Full schema for orders including FKs" -> columns + foreign keys + indexes "Tables starting with user" -> pattern: 'user%'

MCP Resources (db://schema and db://tables/{name}/schema) give AI agents automatic access to your schema — no manual SQL needed for multi-table queries.

Query execution with EXPLAIN

"Show me all users"

-> SELECT * FROM users LIMIT 100 <- auto LIMIT

"Show the execution plan for this query" -> EXPLAIN ANALYZE with dialect-specific syntax (PostgreSQL/MySQL/SQLite)

Compression modes (v0.3+)

SQL results often carry TEXT / JSON / HTML columns that can be kilobytes per row. AI agents pay for every byte that reaches the context window. execute_query, execute_mutation and explain_query accept four optional parameters that cut 60-95% of those tokens while keeping rows and structure intact.

| max_cell_bytes | number (default 500) | Per-cell byte cap for `'nor