db-view-mcp

MCP server that gives AI assistants direct access to PostgreSQL and ClickHouse databases. Supports stdio and HTTP transports, allowing both local IDE integration and remote network access.

Features

• Multi-database — connect to any number of PostgreSQL and ClickHouse instances simultaneously
• Dual transport — stdio for IDE integration (Cursor, Claude Code), HTTP for remote/multi-client access
• Read & write tools — SELECT queries with row limits, INSERT/UPDATE/DELETE, DDL, transactions
• Schema introspection — list tables, describe columns, export full DDL
• Query analysis — EXPLAIN ANALYZE support, slow query tracking
• SQL safety — read-only tools validate SQL to block accidental writes
• Flexible tool modes — single tool with database parameter, or separate tool per database
• Lazy connections — databases connect on first use by default
• Bearer auth — optional token-based authentication for HTTP transport
• Session management — stateful (per-session MCP server) or stateless HTTP mode

Quick start

Install

npm install @conte777/db-view-mcp

Or clone and build from source:

git clone <repo-url>
cd db-view-mcp
npm install
npm run build

Configure

Copy the example config and edit it:

cp config.example.json config.json

Minimal config (stdio, default):

{
  "databases": [
    {
      "id": "main_pg",
      "type": "postgresql",
      "host": "localhost",
      "port": 5432,
      "database": "myapp",
      "user": "admin",
      "password": "secret123"
    }
  ]
}

HTTP transport config:

{
  "transport": {
    "type": "http",
    "port": 3000,
    "host": "127.0.0.1",
    "stateless": false,
    "auth": {
      "type": "bearer",
      "token": "your-secret-token"
    }
  },
  "databases": [
    {
      "id": "main_pg",
      "type": "postgresql",
      "host": "localhost",
      "port": 5432,
      "database": "myapp",
      "user": "admin",
      "password": "secret123"
    }
  ]
}

Run

# Stdio (default)
npm start -- --config config.json

# HTTP via config (set transport.type to "http" in config.json)
npm start -- --config config.json

# HTTP via CLI flag (overrides config)
npm start -- --config config.json --transport http

# Development (no build needed)
npm run dev -- --config config.json

Add to your MCP client

Claude Desktop (claude_desktop_config.json) — stdio:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@conte777/db-view-mcp", "--config", "/path/to/config.json"]
    }
  }
}

Claude Code (.mcp.json) — stdio:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@conte777/db-view-mcp", "--config", "/path/to/config.json"]
    }
  }
}

Any MCP client — HTTP:

# Start the server
node dist/index.js --config config.json --transport http
# Server listens on http://127.0.0.1:3000/mcp

Transport modes

Stdio (default)

Communication via stdin/stdout. Best for local IDE integrations where the MCP client spawns the server process.

HTTP

Uses the MCP Streamable HTTP transport (POST/GET/DELETE /mcp). Best for:

• Remote access over the network
• Multiple clients connecting simultaneously
• Web application integrations

Stateful mode (default): each MCP session gets its own McpServer instance with a unique session ID. All sessions share database connection pools. Supports transactions across requests within the same session.

Stateless mode ("stateless": true): no session management. Each request is independent. Suitable for simple query scenarios without transactions.

HTTP endpoints

| Method | Path | Description | |--------|------|-------------| | POST | /mcp | Send JSON-RPC requests (initialize, tools/call, etc.) | | GET | /mcp | SSE stream for server-to-client notifications | | DELETE | /mcp | Close a session | | GET | /health | Health check — status, active sessions, database list |

Authentication

Optional bearer token authentication:

{
  "transport": {
    "type": "http",
    "auth": {
      "type": "bearer",
      "token": "your-secret-token"
    }
  }
}

Requests to /mcp must include Authorization: Bearer your-secret-token. Requests without a valid token receive 401 Unauthorized. The /health endpoint is not protected.

Example: initialize a session

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "test", "version": "1.0" }
    }
  }'

The response includes a Mcp-Session-Id header. Use it in subsequent requests:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer your-secret-token" \
  -H "Mcp-Session-Id: <session-id-from-init>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

Tools

Read-only

| Tool | Description | |------|-------------| | query | Execute a SELECT query with automatic row limit | | list_databases | List all configured database connections | | list_tables | List tables and views in a schema | | describe_table | Get column names, types, nullability, and primary keys | | schema | Export full DDL for a database | | explain_query | Run EXPLAIN ANALYZE (PostgreSQL) or EXPLAIN (ClickHouse) | | performance | Track and retrieve slow queries, set thresholds |

Write

| Tool | Description | |------|-------------| | execute | Run INSERT, UPDATE, DELETE, or DDL statements | | transaction | Begin, execute within, commit, or rollback transactions (PostgreSQL only) |

Configuration

Transport

| Field | Type | Default | Description | |-------|------|---------|-------------| | transport.type | "stdio" | "http" | "stdio" | Transport mode | | transport.port | number | 3000 | HTTP listen port | | transport.host | string | "127.0.0.1" | HTTP bind address | | transport.stateless | boolean | false | Disable session management | | transport.auth.type | "bearer" | — | Authentication type | | transport.auth.token | string | — | Bearer token value |

The transport field is optional. When omitted, stdio is used. The --transport CLI flag overrides the config value.

Defaults

| Option | Type | Default | Description | |--------|------|---------|-------------| | maxRows | number | 100 | Maximum rows returned by query | | lazyConnection | boolean | true | Connect on first use instead of at startup | | toolsPerDatabase | boolean | false | Register separate tools per database (e.g. query_main_pg) | | queryTimeout | number | 30000 | Query timeout in milliseconds |

PostgreSQL database

| Field | Required | Default | Description | |-------|----------|---------|-------------| | id | yes | — | Unique identifier | | type | yes | — | Must be "postgresql" | | host | yes | — | Hostname | | port | no | 5432 | Port | | database | yes | — | Database name | | user | yes | — | Username | | password | no | "" | Password | | ssl | no | — | Enable SSL | | description | no | — | Human-readable label | | lazyConnection | no | inherits | Override default | | maxRows | no | inherits | Override default | | queryTimeout | no | inherits | Override default |

ClickHouse database

| Field | Required | Default | Description | |-------|----------|---------|-------------| | id | yes | — | Unique identifier | | type | yes | — | Must be "clickhouse" | | url | yes | — | HTTP URL (e.g. http://localhost:8123) | | database | yes | — | Database name | | user | no | "default" | Username | | password | no | "" | Password | | description | no | — | Human-readable label | | lazyConnection | no | inherits | Override default | | maxRows | no | inherits | Override default | | queryTimeout | no | inherits | Override default |

Per-database tool mode

Set "toolsPerDatabase": true in defaults to register a separate tool for each database. Instead of a single query tool with a database parameter, you get query_main_pg, query_analytics, etc. Useful when connecting many databases to avoid parameter confusion.

Architecture

src/
├── index.ts              Entry point: CLI args → config → transport routing
├── server.ts             Creates McpServer + ConnectorManager, registers tools
├── config/
│   ├── types.ts          Zod schemas for config validation (transport, databases)
│   └── loader.ts         Reads config file, parses CLI args (--config, --transport)
├── connectors/
│   ├── interface.ts      Connector interface and shared types
│   ├── manager.ts        Connector lifecycle (lazy/eager, create, disconnect)
│   ├── postgresql.ts     PostgreSQL implementation (pg)
│   └── clickhouse.ts     ClickHouse implementation (@clickhouse/client)
├── tools/
│   ├── registry.ts       Registers tools in parameter or per-database mode
│   ├── readonly/         query, list-tables, describe-table, schema, explain, performance
│   └── write/            execute, transaction
├── transport/
│   └── http.ts           HTTP transport: Express app, session management, auth
└── utils/
    ├── response.ts       Standardized MCP response formatting
    └── sql-validator.ts   Blocks write keywords in read-only queries

ClickHouse limitations

• Transactions are not supported (throws an error)
• Query parameters via params are ignored — use ClickHouse's native {name:Type} syntax in SQL

Development

npm run dev -- --config config.json   # Run with tsx, auto-reload
npm run build                         # Compile TypeScript to dist/
npm start -- --config config.json     # Run compiled output

License

MIT