multi-postgres-mcp-server
One MCP server for all your PostgreSQL databases.
English
Why?
The official @modelcontextprotocol/server-postgres supports only one database per server instance. If you have 5 projects with 5 databases, you need 5 separate MCP server processes.
multi-postgres-mcp-server solves this:
- One server serves all your databases
- One config file with all connections
- Hot reload — add a database to config, it's immediately available (no restart)
--labelfilter — restrict access to a single database per project (isolation)- Read-only — all queries run inside
BEGIN TRANSACTION READ ONLY(safety)
Architecture
┌─────────────────────────────────────────────────────────┐
│ config.json │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ staging │ │production│ │ local │ ... │
│ └──────────┘ └──────────┘ └──────────┘ │
└──────────────────────┬──────────────────────────────────┘
│ reads on every call
▼
┌─────────────────┐
│ mcp-postgres │ ← single MCP server process
│ (stdio) │
└────────┬────────┘
│
┌────────────┼────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│Claude Code│ │ Cursor │ │ Any MCP │
│(all DBs) │ │(filtered)│ │ client │
└──────────┘ └──────────┘ └──────────┘
Tools
Quick Start
1. Install & build
git clone https://github.com/VKirill/multi-postgres-mcp-server.git
cd multi-postgres-mcp-server
npm install
2. Create config
Create ~/.mcp-postgres/config.json (or any path you like):
{
"connections": [
{
"label": "production",
"host": "db.example.com",
"port": 5432,
"user": "readonly_user",
"password": "secret",
"database": "myapp",
"enabled": true
},
{
"label": "staging",
"host": "localhost",
"port": 5432,
"user": "dev",
"password": "dev123",
"database": "myapp_staging",
"enabled": true
}
]
}
Object format also supported (keyed by any identifier):
{
"connections": {
"my-project": { "label": "production", "host": "...", ... }
}
}
3. Add to your AI tool
Claude Code (one command):
claude mcp add postgres -- node /path/to/multi-postgres-mcp-server/dist/index.js
Claude Code (with custom config):
claude mcp add postgres -- node /path/to/multi-postgres-mcp-server/dist/index.js --config /path/to/config.json
Claude Code (with --label for single DB):
claude mcp add postgres -- node /path/to/multi-postgres-mcp-server/dist/index.js --label production
That's it! Claude Code will automatically pick up the server on next start.
Alternative: manual JSON config
Add to ~/.claude.json → mcpServers:
{
"mcpServers": {
"postgres": {
"type": "stdio",
"command": "node",
"args": ["/path/to/multi-postgres-mcp-server/dist/index.js"]
}
}
}
Custom config path
# Via CLI argument
node dist/index.js --config /path/to/my-config.json
# Via environment variable
MCP_POSTGRES_CONFIG=/path/to/config.json node dist/index.js
Default config path: ~/.mcp-postgres/config.json
Usage with Cursor (per-project isolation)
Create .cursor/mcp.json in each project folder:
{
"mcpServers": {
"postgres": {
"command": "node",
"args": [
"/path/to/multi-postgres-mcp-server/dist/index.js",
"--label",
"production"
]
}
}
}
With --label production, the server only exposes the production database. The AI doesn't see other databases and can query directly without choosing.
Usage with Windsurf / Cline / other MCP clients
Same pattern — add as a stdio MCP server:
{
"mcpServers": {
"postgres": {
"command": "node",
"args": ["/path/to/multi-postgres-mcp-server/dist/index.js"]
}
}
}
Example session
User: Show me all tables in the production database
AI calls: pg_list_tables(database="production")
→ Tables in "public" (12):
- users (~45000 rows)
- orders (~128000 rows)
- products (~3200 rows)
...
User: What does the users table look like?
AI calls: pg_describe_table(database="production", table="users")
→ Table "public"."users" (8 columns):
id: integer [PK] NOT NULL DEFAULT nextval('users_id_seq')
email: character varying(255) NOT NULL
name: character varying(100)
created_at: timestamp with time zone DEFAULT now()
...
User: Show me the latest 5 orders
AI calls: pg_query(database="production", query="SELECT * FROM orders ORDER BY created_at DESC LIMIT 5")
→ { columns: [...], rows: [...], rowCount: 5 }
Security
- All queries execute inside
READ ONLYtransactions - Write operations (
INSERT,UPDATE,DELETE,DROP) will fail - Connection timeout: 10 seconds
- Query timeout: 30 seconds
- Config file with passwords is excluded from git via
.gitignore - Use
--labelto prevent AI from accessing unrelated databases
Comparison with official server
Русский
Зачем?
Официальный @modelcontextprotocol/server-postgres поддерживает только одну БД на сервер. Если у вас 5 проектов с 5 базами — нужно 5 отдельных процессов MCP-сервера.
multi-postgres-mcp-server решает это:
- Один сервер обслуживает все БД
- Один конфиг со всеми подключениями
- Hot reload — добавил БД в конфиг, она сразу доступна (без рестарта)
- Фильтр
--label— ограничивает доступ одной БД для проекта (изоляция) - Только чтение — все запросы в
BEGIN TRANSACTION READ ONLY(безопасность)
Архитектура
┌─────────────────────────────────────────────────────────┐
│ config.json │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ staging │ │production│ │ local │ ... │
│ └──────────┘ └──────────┘ └──────────┘ │
└──────────────────────┬──────────────────────────────────┘
│ читает при каждом вызове
▼
┌─────────────────┐
│ mcp-postgres │ ← один процесс MCP-сервера
│ (stdio) │
└────────┬────────┘
│
┌────────────┼────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│Claude Code│ │ Cursor │ │Любой MCP │
│(все БД) │ │(фильтр) │ │ клиент │
└──────────┘ └──────────┘ └──────────┘
Инструменты
Быстрый старт
1. Установка
git clone https://github.com/VKirill/multi-postgres-mcp-server.git
cd multi-postgres-mcp-server
npm install
2. Создайте конфиг
~/.mcp-postgres/config.json:
{
"connections": [
{
"label": "production",
"host": "db.example.com",
"port": 5432,
"user": "readonly_user",
"password": "secret",
"database": "myapp",
"enabled": true
}
]
}
3. Добавьте в Claude Code
Одной командой:
claude mcp add postgres -- node /path/to/multi-postgres-mcp-server/dist/index.js
С кастомным конфигом:
claude mcp add postgres -- node /path/to/multi-postgres-mcp-server/dist/index.js --config /path/to/config.json
С фильтром на одну БД:
claude mcp add postgres -- node /path/to/multi-postgres-mcp-server/dist/index.js --label production
Готово! Claude Code подхватит сервер при следующем запуске.
Cursor (изоляция по проектам)
В каждой папке проекта создайте .cursor/mcp.json:
{
"mcpServers": {
"postgres": {
"command": "node",
"args": [
"/path/to/multi-postgres-mcp-server/dist/index.js",
"--label",
"production"
]
}
}
}
С --label production сервер видит только БД production. ИИ не знает про другие базы и может сразу делать запросы без выбора.
Путь к конфигу
node dist/index.js --config /path/to/config.json
# или
MCP_POSTGRES_CONFIG=/path/to/config.json node dist/index.js
По умолчанию: ~/.mcp-postgres/config.json
Сравнение с официальным сервером
Безопасность
- Все запросы выполняются в
READ ONLYтранзакциях - Операции записи (
INSERT,UPDATE,DELETE,DROP) завершатся ошибкой - Таймаут подключения: 10 сек, таймаут запроса: 30 сек
- Конфиг с паролями исключён из git через
.gitignore --labelне даёт ИИ видеть чужие базы данных
中文
为什么需要？
官方 @modelcontextprotocol/server-postgres 每个服务器实例只支持一个数据库。如果你有5个项目对应5个数据库，就需要5个独立的MCP服务器进程。
multi-postgres-mcp-server 解决了这个问题：
- 一个服务器管理所有数据库
- 一个配置文件包含所有连接
- 热重载 — 在配置中添加数据库，立即可用（无需重启）
--label过滤器 — 限制项目只能访问单个数据库（隔离）- 只读模式 — 所有查询在
BEGIN TRANSACTION READ ONLY中执行（安全）
架构
┌─────────────────────────────────────────────────────────┐
│ config.json │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ staging │ │production│ │ local │ ... │
│ └──────────┘ └──────────┘ └──────────┘ │
└──────────────────────┬──────────────────────────────────┘
│ 每次调用时读取
▼
┌─────────────────┐
│ mcp-postgres │ ← 单个MCP服务器进程
│ (stdio) │
└────────┬────────┘
│
┌────────────┼────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│Claude Code│ │ Cursor │ │任意 MCP │
│(所有数据库)│ │(已过滤) │ │ 客户端 │
└──────────┘ └──────────┘ └──────────┘
工具
快速开始
1. 安装
git clone https://github.com/VKirill/multi-postgres-mcp-server.git
cd multi-postgres-mcp-server
npm install
2. 创建配置
~/.mcp-postgres/config.json：
{
"connections": [
{
"label": "production",
"host": "db.example.com",
"port": 5432,
"user": "readonly_user",
"password": "secret",
"database": "myapp",
"enabled": true
}
]
}
3. 添加到 Claude Code
一条命令：
claude mcp add postgres -- node /path/to/multi-postgres-mcp-server/dist/index.js
自定义配置路径：
claude mcp add postgres -- node /path/to/multi-postgres-mcp-server/dist/index.js --config /path/to/config.json
单数据库过滤：
claude mcp add postgres -- node /path/to/multi-postgres-mcp-server/dist/index.js --label production
完成！Claude Code 将在下次启动时自动加载服务器。
Cursor（按项目隔离）
在每个项目文件夹中创建 .cursor/mcp.json：
{
"mcpServers": {
"postgres": {
"command": "node",
"args": [
"/path/to/multi-postgres-mcp-server/dist/index.js",
"--label",
"production"
]
}
}
}
使用 --label production 后，服务器只暴露 production 数据库。AI看不到其他数据库，可以直接查询无需选择。
配置路径
node dist/index.js --config /path/to/config.json
# 或
MCP_POSTGRES_CONFIG=/path/to/config.json node dist/index.js
默认路径：~/.mcp-postgres/config.json
与官方服务器对比
安全性
- 所有查询在
READ ONLY事务中执行 - 写操作（
INSERT、UPDATE、DELETE、DROP）会失败 - 连接超时：10秒，查询超时：30秒
- 包含密码的配置文件通过
.gitignore排除在git之外 --label防止AI访问无关数据库
License
MIT
