# MCP Database Server

Give any AI agent (Claude Desktop, Cursor, OpenClaw, etc.) direct, **natural language** access to your PostgreSQL or MySQL database.

Instead of writing SQL, your agent asks questions like *"show me the top 10 customers by revenue"* — and gets the answer instantly.

## What it does

| Tool | Description |
|---|---|
| `query` | Run raw SQL (parameterized, injection-safe). Supports SELECT, INSERT, UPDATE, DELETE. |
| `schema` | Discover all tables, columns, data types, primary/foreign keys. Agent uses this to understand your data. |
| `analyze` | Pre-built aggregations (count, sum, avg, top-N, group-by) without writing SQL. |

## Quick start

### Option A: Docker Compose (recommended)

```bash
# 1. Clone
git clone https://github.com/Lucasyao1985/mcp-database-server.git
cd mcp-database-server

# 2. Start Postgres + MCP server
docker compose up

# Done — the MCP server is running.
```

### Option B: Standalone

```bash
git clone https://github.com/Lucasyao1985/mcp-database-server.git
cd mcp-database-server
npm install
cp .env.example .env
# Edit .env → add your DATABASE_URL
npm run build && npm start
```

## Connect to Claude Desktop

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "database": {
      "command": "docker",
      "args": [
        "exec", "-i",
        "mcp-database-server-mcp-database-1",
        "node", "dist/index.js"
      ]
    }
  }
}
```

> For non-Docker setups, use `"command": "node"` and `"args": ["/absolute/path/to/dist/index.js"]`.

## Example conversation

> **You**: What tables are in my database?
>
> **Agent**: *[calls `schema`]* — Found 4 tables: `customers`, `orders`, `products`, `order_items`.
>
> **You**: Show me the top 5 customers by total spend.
>
> **Agent**: *[calls `analyze`]* — 1. Acme Corp: $48,200, 2. Globex: $31,500, ...

## Security

- **SQL injection protection**: All queries use parameterized `$1, $2, ...` placeholders. Never interpolate user input directly.
- **Read-only mode**: Set `READ_ONLY=true` in `.env` to block INSERT/UPDATE/DELETE.
- **No data leaves your infrastructure**: Everything runs locally. No telemetry.

## Tech stack

- [MCP SDK](https://github.com/modelcontextprotocol/sdk) — Model Context Protocol
- Node.js / TypeScript
- PostgreSQL (primary) / MySQL (supported)
- Docker Compose for one-command deployment

## Demo (video coming soon)

See the server in action: connect to Claude Desktop → ask a question → get live database results.

---

**Built on the [Model Context Protocol](https://modelcontextprotocol.io/).**