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)
--label filter — 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

Tool	Parameters	Description
`pg_list_databases`	—	List all available databases
`pg_query`	`database`, `query`	Execute read-only SQL query
`pg_list_tables`	`database`, `schema?`	List tables with row counts
`pg_describe_table`	`database`, `table`, `schema?`	Column types, PK, FK, defaults

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 ONLY transactions
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 --label to prevent AI from accessing unrelated databases

Comparison with official server

Feature	`@modelcontextprotocol/server-postgres`	`multi-postgres-mcp-server`
Databases per server	1	Unlimited
Config format	Connection string in args	JSON file
Hot reload	No (restart required)	Yes
Per-project isolation	N/A	`--label` filter
Query safety	Full access	Read-only only
Processes needed for 5 DBs	5	1

Русский

Зачем?

Официальный @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 │
    │(все БД)  │ │(фильтр)  │ │ клиент   │
    └──────────┘ └──────────┘ └──────────┘

Инструменты

Инструмент	Параметры	Описание
`pg_list_databases`	—	Список доступных БД
`pg_query`	`database`, `query`	Read-only SQL запрос
`pg_list_tables`	`database`, `schema?`	Таблицы с количеством строк
`pg_describe_table`	`database`, `table`, `schema?`	Колонки, типы, PK, FK, defaults

Быстрый старт

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

Сравнение с официальным сервером

Возможность	`@modelcontextprotocol/server-postgres`	`multi-postgres-mcp-server`
БД на сервер	1	Без ограничений
Формат конфига	Connection string в аргументах	JSON файл
Hot reload	Нет (нужен рестарт)	Да
Изоляция по проектам	Нет	Фильтр `--label`
Безопасность запросов	Полный доступ	Только чтение
Процессов для 5 БД	5	1

Безопасность

Все запросы выполняются в 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  │
    │(所有数据库)│ │(已过滤)  │ │ 客户端   │
    └──────────┘ └──────────┘ └──────────┘

工具

工具	参数	描述
`pg_list_databases`	—	列出所有可用数据库
`pg_query`	`database`, `query`	执行只读SQL查询
`pg_list_tables`	`database`, `schema?`	列出表及行数估计
`pg_describe_table`	`database`, `table`, `schema?`	列类型、主键、外键、默认值

快速开始

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

与官方服务器对比

功能	`@modelcontextprotocol/server-postgres`	`multi-postgres-mcp-server`
每服务器数据库数	1	无限制
配置格式	参数中的连接字符串	JSON 文件
热重载	否（需重启）	是
按项目隔离	无	`--label` 过滤器
查询安全性	完全访问	仅只读
5个数据库需要的进程数	5	1

安全性

所有查询在 READ ONLY 事务中执行
写操作（INSERT、UPDATE、DELETE、DROP）会失败
连接超时：10秒，查询超时：30秒
包含密码的配置文件通过 .gitignore 排除在git之外
--label 防止AI访问无关数据库

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.github/workflows		.github/workflows
src		src
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
config.example.json		config.example.json
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

License

VKirill/multi-postgres-mcp-server

Folders and files

Latest commit

History

Repository files navigation

multi-postgres-mcp-server

English

Why?

Architecture

Tools

Quick Start

1. Install & build

2. Create config

3. Add to your AI tool

Alternative: manual JSON config

Custom config path

Usage with Cursor (per-project isolation)

Usage with Windsurf / Cline / other MCP clients

Example session

Security

Comparison with official server

Русский

Зачем?

Архитектура

Инструменты

Быстрый старт

1. Установка

2. Создайте конфиг

3. Добавьте в Claude Code

Cursor (изоляция по проектам)

Путь к конфигу

Сравнение с официальным сервером

Безопасность

中文

为什么需要？

架构

工具

快速开始

1. 安装

2. 创建配置

3. 添加到 Claude Code

Cursor（按项目隔离）

配置路径

与官方服务器对比

安全性

License

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Contributors 2

Uh oh!

Languages

Packages