# DB MCP Server

Open-source MCP server owned by **Pawan Gunjkar** (`pawangunjkar@gmail.com` · [GitHub](https://github.com/Pawangunjkar)). MIT licensed.

Developers ask the editor to inspect and change data without opening a SQL client, Mongo shell, redis-cli, or Kibana. The server speaks MCP over stdio, keeps named sessions, and routes each session to the right engine.

Sibling servers: [github-mcp](https://github.com/Pawangunjkar/github-mcp), [jenkins-mcp](https://github.com/Pawangunjkar/jenkins-mcp), [linux-ssh-mcp](https://github.com/Pawangunjkar/linux-ssh-mcp), [observability-mcp](https://github.com/Pawangunjkar/observability-mcp), [k8s-mcp](https://github.com/Pawangunjkar/k8s-mcp).

## Project information

| Item | Value |
| --- | --- |
| Package | `pawangunjkar-db-mcp` |
| Runtime | Python 3.10+, FastMCP, stdio |
| SQL | PostgreSQL, MySQL, MariaDB, SQLite, Oracle, SQL Server |
| NoSQL | MongoDB, Redis, Elasticsearch |
| Safety | `WHERE` required on update/delete. `DROP` / `TRUNCATE` / `ALTER` and deletes need `confirm=true`. `DB_ALLOW_WRITE=false` makes the session read-only |

## Architecture

```mermaid
flowchart TB
  subgraph L1["Layer 1 — Editor"]
    IDE["Cursor or Claude Desktop"]
  end

  subgraph L2["Layer 2 — MCP"]
    SRV["db-mcp FastMCP server"]
    HUB["DbHub named sessions"]
  end

  subgraph L3["Layer 3 — Drivers"]
    SA["SQLAlchemy"]
    MG["PyMongo"]
    RD["redis-py"]
    ES["HTTP client"]
  end

  subgraph L4["Layer 4 — Databases"]
    PG["PostgreSQL / MySQL / SQLite"]
    OR["Oracle / SQL Server"]
    MO["MongoDB"]
    RE["Redis"]
    EL["Elasticsearch"]
  end

  IDE -->|"db_query / db_insert / mongo_find"| SRV
  SRV --> HUB
  HUB --> SA
  HUB --> MG
  HUB --> RD
  HUB --> ES
  SA --> PG
  SA --> OR
  MG --> MO
  RD --> RE
  ES --> EL
```

A chat message becomes one tool call. The hub picks the session, the driver binds parameters, and the database returns rows or a write count. The editor never opens a second window.

```mermaid
flowchart LR
  Q["db_connect"] --> S["Session"]
  S --> R["db_query / db_describe_table"]
  S --> W["db_insert / db_update"]
  W --> C{"confirm or WHERE?"}
  C -->|yes| DB[("Database")]
  C -->|no| STOP["Refused"]
  R --> DB
```

## Engines

| Kind | Engine | URL example |
| --- | --- | --- |
| SQL | `postgresql` | `postgresql+psycopg://user:pass@localhost:5432/ecs_oms` |
| SQL | `mysql` / `mariadb` | `mysql+pymysql://user:pass@localhost:3306/app` |
| SQL | `oracle` | `oracle+oracledb://user:pass@localhost:1521/?service_name=ORCLPDB` |
| SQL | `sqlserver` | `mssql+pymssql://user:pass@localhost:1433/app` |
| SQL | `sqlite` | `sqlite:///C:/data/app.db` |
| NoSQL | `mongodb` | `mongodb://localhost:27017` |
| NoSQL | `redis` | `redis://localhost:6379/0` |
| NoSQL | `elasticsearch` | `http://localhost:9200` |

Oracle uses the python-oracledb thin mode, so the Instant Client is not required. CockroachDB and Amazon Aurora PostgreSQL use the `postgresql` engine.

## Read tools

`db_query`, `db_list_tables`, `db_describe_table`, `mongo_find`, `mongo_list_databases`, `mongo_list_collections`, `redis_get`, `redis_keys`, `es_search`

## Write tools

`db_insert`, `db_update`, `db_delete`, `db_execute`, `mongo_insert`, `mongo_update`, `mongo_delete`, `redis_set`, `redis_delete`, `es_index_document`, `es_delete_document`

`UPDATE` and `DELETE` require a `WHERE` clause. `DROP`, `TRUNCATE`, `ALTER`, Mongo deletes, and Elasticsearch deletes require `confirm=true`. Set `DB_ALLOW_WRITE=false` to make a session read-only.

## Cursor

```json
{
  "mcpServers": {
    "db": {
      "command": "uv",
      "args": ["run", "--directory", "C:/AI_Workspaces/Anti_Workspace/db-mcp", "server.py"],
      "env": {
        "DB_ENGINE": "postgresql",
        "DB_URL": "postgresql+psycopg://ecs:ecs_secret@localhost:5432/ecs_oms",
        "DB_ALLOW_WRITE": "true"
      }
    }
  }
}
```