# MCP Database Server

An MCP server that connects PostgreSQL and MySQL to your agent and turns plain-language questions into SQL. Handy when you want to inspect data without writing queries by hand.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 19
- Author: Souhar-dya
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Souhar-dya/mcp-db-server
- Updated: 2026-09-13
- HTML: https://affpapa.org/en/nevibecode/mcp/mcp-database-server

## What it does

The server runs a FastAPI app and hands your agent table listings, a table's schema, sample rows, and query execution. A question like "top 5 customers by total order amount" goes through HuggingFace transformers, which produces the SQL and a structured result.

Operations are read-only, queries get validated, and result size is capped. Since version 1.4.0 the database HTTP routes require an `X-API-Key` header; only `/health` stays public. Without `MCP_API_KEY` set, those routes are disabled, so plan for the key up front. The same release binds to `127.0.0.1` by default, checks table names against the real schema, and supports `sslmode=require` for `asyncpg`.

Docker Compose is the shortest path: clone the repo, generate a key with `openssl rand -hex 32`, bring the containers up. Running locally needs Python 3.11+ and the packages from `requirements.txt`. A demo e-commerce database ships with the project, which is a reasonable way to test the wiring before pointing it at a real database.

## Requirements
- Needs: Docker
- Environment variables: `DATABASE_URL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env DATABASE_URL=<DATABASE_URL> --transport stdio mcp-database-server -- docker run -i --rm -e DATABASE_URL docker.io/souhardyak/mcp-db-server:1.3.1
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add mcp-database-server --env DATABASE_URL=<DATABASE_URL> -- docker run -i --rm -e DATABASE_URL docker.io/souhardyak/mcp-db-server:1.3.1
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "mcp-database-server": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "DATABASE_URL",
                "docker.io/souhardyak/mcp-db-server:1.3.1"
            ],
            "env": {
                "DATABASE_URL": "<DATABASE_URL>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "mcp-database-server": {
            "type": "stdio",
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "DATABASE_URL",
                "docker.io/souhardyak/mcp-db-server:1.3.1"
            ],
            "env": {
                "DATABASE_URL": "<DATABASE_URL>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e DATABASE_URL=<DATABASE_URL> mcp-database-server docker run -i --rm -e DATABASE_URL docker.io/souhardyak/mcp-db-server:1.3.1
```
Replace <…> with your own values

## When to use it
- inspect table contents without opening psql
- pull a table schema into the agent chat
- phrase a SQL query in words and see the rows
- grab a few sample rows to sanity-check data
- wire PostgreSQL or MySQL into an agent without writing code

## Example prompts
- List the tables in the database and how many columns each has
- Describe the schema of the `customers` table
- Count orders grouped by status

## Similar
- [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89408
- [Scrapling MCP Server](https://affpapa.org/en/nevibecode/mcp/scrapling-mcp-server.md) — MCP server · ★ 89433
- [MCP Toolbox for Databases](https://affpapa.org/en/nevibecode/mcp/googleapis-mcp-toolbox-for-databases.md) — MCP server · ★ 16717
- [PostHog MCP Server](https://affpapa.org/en/nevibecode/mcp/posthog-mcp-server.md) — MCP server · ★ 40409
- [dbx](https://affpapa.org/en/nevibecode/mcp/dbx.md) — MCP server · ★ 27669
- [Metabase](https://affpapa.org/en/nevibecode/mcp/metabase.md) — MCP server · ★ 49845

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md