Позволяет AI-агентам взаимодействовать с базами данных PostgreSQL с помощью специализированных инструментов, интроспекции схем и безопасного изолята V8 для выполнения сложных операций.
Также известен как neverinfamous/postgres-mcp, postgres-mcp
- Звёзды
- 12
- Инструменты
- 25
- Загрузки, 30 дней
- —
- Последняя версия
- 1.2.0
- Последний коммит
- 28 сент. 2026 г.
- Лицензия
- MIT
Что такое PostgreSQL MCP?
Позволяет AI-агентам взаимодействовать с базами данных PostgreSQL с помощью специализированных инструментов, интроспекции схем и безопасного изолята V8 для выполнения сложных операций. Он предоставляет 25 инструментов, например codemode, core, transactions.
Сводка сгенерирована из README проекта
О PostgreSQL MCP server
Этот сервер позволяет подключать AI-агентов к базам данных PostgreSQL для сложного управления данными. Он предоставляет огромный набор из 278 специализированных инструментов, разработанных для снижения расхода токенов и повышения точности. Разработчики могут использовать его локально через Node.js или через Docker, подключаясь к локальным, контейнеризированным или удаленным облачным базам данных, таким как AWS RDS, Google Cloud SQL или Supabase, используя стандартные строки подключения.
Отличительной особенностью является Code Mode, который использует безопасный изолят V8 через worker_threads для выполнения многоэтапных операций. Такой подход может снизить потребление токенов AI на величину до 90% по сравнению с традиционными последовательными вызовами инструментов. Сервер также включает интроспекцию схем, отслеживание миграций и поддержку различных расширений, включая pgvector, PostGIS и pg_cron. Безопасность обеспечивается через OAuth 2.1 с гранулярными областями доступа (scopes), а детерминированная обработка ошибок преобразует необработанные исключения SQL в полезные инструкции для агента.
Что вы можете с ним делать
- 1Выполнение сложных многоэтапных операций с базой данныхИспользуйте Code Mode для запуска сложной логики внутри безопасного изолята V8, чтобы сэкономить на стоимости токенов.
- 2Безопасное управление изменениями схемы базы данныхПопросите AI-агента смоделировать влияние обновлений схемы и отследить историю миграций.
- 3Мониторинг состояния и производительности базы данныхПредоставьте AI-агенту метрики в реальном времени для диагностики проблем с базой данных.
Взято из README проекта. Каждый вариант использования проверен на соответствие цитате из него.
Как установить PostgreSQL MCP
Форматы проверены 10 ноя 2026Добавить в CursorДобавить в GooseУстановка PostgreSQL MCP в Claude Code
$ claude mcp add postgres-mcp -- docker run -i --rm docker.io/writenotenow/postgres-mcp-enhanced:v1.2.0Установка PostgreSQL MCP в Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"postgres-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/writenotenow/postgres-mcp-enhanced:v1.2.0"
]
}
}
}Установка PostgreSQL MCP в VS Code
.vscode/mcp.json
{
"servers": {
"postgres-mcp": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/writenotenow/postgres-mcp-enhanced:v1.2.0"
]
}
}
}Установка PostgreSQL MCP в VS Code CLI
$ code --add-mcp '{"name":"postgres-mcp","type":"stdio","command":"docker","args":["run","-i","--rm","docker.io/writenotenow/postgres-mcp-enhanced:v1.2.0"]}'Установка PostgreSQL MCP в Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"postgres-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/writenotenow/postgres-mcp-enhanced:v1.2.0"
]
}
}
}Установка PostgreSQL MCP в Codex
$ codex mcp add postgres-mcp -- docker run -i --rm docker.io/writenotenow/postgres-mcp-enhanced:v1.2.0Установка PostgreSQL MCP в Codex config.toml
~/.codex/config.toml
[mcp_servers.postgres-mcp] command = "docker" args = ["run", "-i", "--rm", "docker.io/writenotenow/postgres-mcp-enhanced:v1.2.0"]
Установка PostgreSQL MCP в Gemini CLI
$ gemini mcp add -s user postgres-mcp docker -- run -i --rm docker.io/writenotenow/postgres-mcp-enhanced:v1.2.0Установка PostgreSQL MCP в Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"postgres-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/writenotenow/postgres-mcp-enhanced:v1.2.0"
]
}
}
}Инструменты PostgreSQL MCP 25
Определено из READMEcodemodecoretransactionsjsonbtextperformanceadminmonitoringbackupschemaintrospectionmigration
| codemode | — | |
| core | — | |
| transactions | — | |
| jsonb | — | |
| text | — | |
| performance | — | |
| admin | — | |
| monitoring | — | |
| backup | — | |
| schema | — | |
| introspection | — | |
| migration | — |
Показать все 25 инструментовПоказать меньше инструментов
partitioningstatsvectorpostgiscronpartmankcachecitextltreepgcryptosecurityrolesdocstore
| partitioning | — | |
| stats | — | |
| vector | — | |
| postgis | — | |
| cron | — | |
| partman | — | |
| kcache | — | |
| citext | — | |
| ltree | — | |
| pgcrypto | — | |
| security | — | |
| roles | — | |
| docstore | — |
Конфигурация
MCP_AUTH_TOKENPOSTGRES_DATABASEPOSTGRES_HOSTPOSTGRES_PASSWORDPOSTGRES_PORTPOSTGRES_USER
| Название | Описание | Тип |
|---|---|---|
| MCP_AUTH_TOKEN | — | |
| POSTGRES_DATABASE | — | |
| POSTGRES_HOST | — | |
| POSTGRES_PASSWORD | — | |
| POSTGRES_PORT | — | |
| POSTGRES_USER | — |
Автоматические проверки
Запущено 12 нояб. 2026 г.Полный отчёт →Прошло наши автоматизированные проверки. Это не аудит безопасности: изучите код и предоставьте серверу минимально необходимый доступ. Как работают проверки
- Связанный и доступный исходный репозиторийПройдено
- Open source лицензия (OSI)Пройдено
- Коммит или релиз за последний годПройдено
- Имя пакета не похоже на популярный пакетНе проверялось
- Удаленная конечная точка использует HTTPSНе проверялось
- Деструктивные инструменты помеченыПройдено
- Нет скрытых инструкций для моделиПройдено
- Нет критических предупреждений в пакете или его зависимостяхНе проверялось
README
Открыть на GitHubpostgres-mcp
PostgreSQL MCP Server binding the Model Context Protocol to a secure PostgreSQL sandbox.
Features Code Mode — a revolutionary approach that provides access to all 278 tools through a secure, true V8 isolate (worker_threads), eliminating the massive token overhead of multi-step tool calls. Also includes schema introspection, migration tracking, smart tool filtering, deterministic error handling, connection pooling, HTTP/SSE Transport, OAuth 2.1 authentication, and extension support for citext, ltree, pgcrypto, pg_cron, pg_stat_kcache, pgvector, PostGIS, and HypoPG.
278 Specialized Tools · 24 Resources · 21 AI-Powered Prompts
Docker Hub • npm Package • MCP Registry • Wiki • Tool Reference • Changelog
🎯 What Sets Us Apart
| Feature | Description |
|---|---|
| Code Mode (V8 Isolate) | Massive Token Savings: Execute complex, multi-step operations inside a secure, true V8 isolate (worker_threads). Stop burning tokens on back-and-forth tool calls and reduce your AI overhead by up to 90%. |
| Deterministic Error Handling | No more cryptic database errors causing AI hallucinations. We intercept and translate raw SQL exceptions into clear, actionable advice so your agent knows exactly how to recover without guessing. |
| 278 Token-Optimized Tools | The largest PostgreSQL toolset on the MCP registry. Every query uses zero-cost token estimation and smart dataset truncation, ensuring agents always see the big picture without blowing their context windows. |
| OAuth 2.1 + Granular Control | Real enterprise security. Authenticate via OAuth 2.1 and control exactly who can read, write, or administer your database with precision scopes mapped down to the specific tool layer. |
| Audit Trails & Semantic Diffing | Total accountability. Track exactly what your AI is doing with detailed JSON logs, automatically snapshot schemas before mutations, and confidently review semantic row-by-row diffs before restoring data. |
| 24 Resources & 21 Prompts | Instant database meta-awareness. Agents automatically read real-time health, performance, and replication metrics, and can invoke built-in prompt workflows for query tuning and schema design. |
| Introspection & Migrations | Prevent costly mistakes. Let your AI simulate the cascade impact of schema changes, safely order foreign-key updates, and track migration history automatically. |
| 8 Extension Ecosystems | Ready for advanced workloads. First-class API support for pgvector (AI search), PostGIS (geospatial), pg_cron, pgcrypto, and more—all strictly typed and validated out of the box. |
| Smart Tool Filtering | Give your agent exactly what it needs without overflowing IDE limits. Dynamically compile your server with any combination of our 25 distinct tool groups. |
| Enterprise Infrastructure | Built for production. Blazing fast (millions of ops/sec), protected against SQL injection, features high-performance connection pooling, and supports both Streamable HTTP and Legacy SSE protocols simultaneously. |
Suggested Rule (Add to AGENTS.md, GEMINI.md, etc)
MCP TOKEN MANAGEMENT:
- Token Visibility: When interacting with
postgres-mcp, always monitor the_meta.tokenEstimate(ormetrics.tokenEstimatein Code Mode) returned in tool responses. - Audit Resource: Use the
postgres://auditresource to review session-level token consumption and identify high-cost operations. - Proactive Efficiency: If operations are consuming high token counts, prefer code mode and proactively use
limitparameters.
🚀 Quick Start
Prerequisites
- PostgreSQL 12-18 (tested with PostgreSQL 18.1)
- Docker (recommended) or Node.js 24+ (LTS)
Docker (Recommended)
docker pull writenotenow/postgres-mcp:latest
Add to your ~/.cursor/mcp.json or Claude Desktop config:
{
"mcpServers": {
"postgres-mcp": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"POSTGRES_HOST",
"-e",
"POSTGRES_PORT",
"-e",
"POSTGRES_USER",
"-e",
"POSTGRES_PASSWORD",
"-e",
"POSTGRES_DATABASE",
"writenotenow/postgres-mcp:latest",
"--tool-filter",
"codemode",
"--audit-log",
"/tmp/postgres-logs/audit.jsonl"
],
"env": {
"POSTGRES_HOST": "host.docker.internal",
"POSTGRES_PORT": "5432",
"POSTGRES_USER": "your_username",
"POSTGRES_PASSWORD": "your_password",
"POSTGRES_DATABASE": "your_database"
}
}
}
}
Note for Docker: Use
host.docker.internalto connect to PostgreSQL running on your host machine.
📖 Full Docker guide: DOCKER_README.md · Docker Hub
npm
npm install -g @neverinfamous/postgres-mcp
postgres-mcp --transport stdio --postgres postgres://user:password@localhost:5432/database
From Source
git clone https://github.com/neverinfamous/postgres-mcp.git
cd postgres-mcp
npm install
npm run build
node dist/cli.js --transport stdio --postgres postgres://user:password@localhost:5432/database
Development
See From Source above for setup. After cloning:
npm run lint && npm run typecheck # Run checks
npm run bench # Run performance benchmarks
node dist/cli.js info # Test CLI
node dist/cli.js list-tools # List available tools
Benchmarks
Run npm run bench to execute the performance benchmark suite (10 files, 93+ scenarios) powered by Vitest Bench. Use npm run bench:verbose for detailed table output.
Performance Highlights (Node.js 24, Windows 11):
| Area | Benchmark | Throughput |
|---|---|---|
| Tool Dispatch | Map.get() single tool lookup | ~6.9M ops/sec |
| WHERE Validation | Simple clause (combined regex fast-path) | ~3.7M ops/sec |
| Identifier Sanitization | validateIdentifier() | ~4.4M ops/sec |
| Auth — Token Extraction | extractBearerToken() | ~2.7M ops/sec |
| Auth — Scope Checking | hasScope() | ~5.3M ops/sec |
| Rate Limiting | Single IP check | ~2.3M ops/sec |
| Logger | Filtered debug (no-op path) | ~5.4M ops/sec |
| Schema Parsing | MigrationInitSchema.parse() | ~2.1M ops/sec |
| Metadata Cache | Cache hit + miss pattern | ~1.7M ops/sec |
| Sandbox Creation | CodeModeSandbox.create() cold start | ~863 ops/sec |
Full benchmark results and methodology are available on the Performance wiki page.
🔗 Database Connection Scenarios
| Scenario | Host to Use | Example Connection String |
|---|---|---|
| PostgreSQL on host machine | localhost or host.docker.internal |
postgres://user:pass@localhost:5432/db |
| PostgreSQL in Docker | Container name or network | postgres://user:pass@postgres-container:5432/db |
| Remote/Cloud PostgreSQL | Hostname or IP | postgres://user:pass@db.example.com:5432/db |
| Provider | Example Hostname |
|---|---|
| AWS RDS PostgreSQL | your-instance.xxxx.us-east-1.rds.amazonaws.com |
| Google Cloud SQL | project:region:instance (via Cloud SQL Proxy) |
| Azure PostgreSQL | your-server.postgres.database.azure.com |
| Supabase | db.xxxx.supabase.co |
| Neon | ep-xxx.us-east-1.aws.neon.tech |
🛠️ Tool Filtering
[!IMPORTANT] All tool groups include Code Mode (
pg_execute_code) by default. To exclude it, add-codemodeto your filter:--tool-filter cron,pgcrypto,-codemode
💡 Code Mode (
--tool-filter codemode) is the recommended configuration — it exposespg_execute_code, a secure, true V8 isolate sandbox providing access to all 278 tools' worth of capability with up to 90% token savings. See Tool Filtering for alternatives.
- Requires
adminOAuth scope — execution is logged for audit
📖 See Full Installation Guide →
What Can You Filter?
The --tool-filter argument accepts groups or tool names — mix and match freely:
| Filter Pattern | Example | Description |
|---|---|---|
| Groups only | core,jsonb,transactions |
Combine individual groups |
| Tool names | pg_read_query,pg_explain |
Custom tool selection |
| Group + Tool | core,+pg_stat_statements |
Extend a group |
| Group - Tool | core,-pg_drop_table |
Remove specific tools |
Tool Groups (25 Available)
| Group | Tools | Description |
|---|---|---|
codemode |
1 | Code Mode (sandboxed code execution) 🌟 Recommended |
core |
21 | Read/write queries, tables, indexes, convenience/drop tools |
transactions |
9 | BEGIN, COMMIT, ROLLBACK, savepoints, status |
jsonb |
21 | JSONB manipulation, queries, and pretty-print |
text |
14 | Full-text search, fuzzy matching |
performance |
25 | EXPLAIN, query analysis, optimization, diagnostics, anomaly detection |
admin |
12 | VACUUM, ANALYZE, REINDEX, insights |
monitoring |
12 | Database sizes, connections, status |
backup |
13 | pg_dump, COPY, restore, audit backups |
schema |
13 | Schemas, views, sequences, functions, triggers |
introspection |
7 | Dependency graphs, cascade simulation, schema analysis |
migration |
7 | Schema migration tracking and management |
partitioning |
7 | Native partition management |
stats |
20 | Statistical analysis, window functions, outlier detection |
vector |
17 | pgvector (AI/ML similarity search) |
postgis |
16 | PostGIS (geospatial) |
cron |
9 | pg_cron (job scheduling) |
partman |
11 | pg_partman (auto-partitioning) |
kcache |
8 | pg_stat_kcache (OS-level stats) |
citext |
7 | citext (case-insensitive text) |
ltree |
9 | ltree (hierarchical data) |
pgcrypto |
10 | pgcrypto (encryption, UUIDs) |
security |
10 | Security auditing, SSL, firewall, data masking, privilege analysis |
roles |
13 | Role management, privileges, membership, RLS |
docstore |
10 | JSONB document collections (NoSQL-style CRUD, indexing) |
Syntax Reference
| Prefix | Target | Example | Effect |
|---|---|---|---|
| (none) | Group | core |
Whitelist Mode: Enable ONLY this group |
| (none) | Tool | pg_read_query |
Whitelist Mode: Enable ONLY this tool |
+ |
Group | +vector |
Add tools from this group to current set |
- |
Group | -admin |
Remove tools in this group from current set |
+ |
Tool | +pg_explain |
Add one specific tool |
- |
Tool | -pg_drop_table |
Remove one specific tool |
🌐 HTTP/SSE Transport (Remote Access)
For remote access, web-based clients, or HTTP-compatible MCP hosts, use the HTTP transport:
node dist/cli.js \
--transport http \
--port 3000 \
--postgres "postgres://user:pass@localhost:5432/db"
Docker:
docker run --rm -p 3000:3000 \
-e POSTGRES_URL=postgres://user:pass@host:5432/db \
writenotenow/postgres-mcp:latest \
--transport http --port 3000
The server supports two MCP transport protocols simultaneously, enabling both modern and legacy clients to connect:
Streamable HTTP (Recommended)
Modern protocol (MCP 2025-03-26) — single endpoint, session-based:
| Method | Endpoint | Purpose |
|---|---|---|
POST |
/mcp |
JSON-RPC requests (initialize, tools/list, etc.) |
GET |
/mcp |
SSE stream for server notifications |
DELETE |
/mcp |
Session termination |
Sessions are managed via the Mcp-Session-Id header.
Stateless Mode
For serverless/stateless deployments where sessions are not needed:
node dist/cli.js --transport http --port 3000 --stateless --postgres "postgres://..."
In stateless mode: GET /mcp returns 405, DELETE /mcp returns 204, /sse and /messages return 404. Each POST /mcp creates a fresh transport.
Legacy SSE (Backward Compatibility)
Legacy protocol (MCP 2024-11-05) — for clients like Python mcp.client.sse:
| Method | Endpoint | Purpose |
|---|---|---|
GET |
/sse |
Opens SSE stream, returns /messages?sessionId=<id> endpoint |
POST |
/messages?sessionId=<id> |
Send JSON-RPC messages to the session |
Utility Endpoints
| Method | Endpoint | Purpose |
|---|---|---|
GET |
/health |
Health check (bypasses rate limiting, always available for monitoring) |
🔐 Authentication
postgres-mcp supports two authentication mechanisms for HTTP transport:
Simple Bearer Token (--auth-token)
Lightweight authentication for development or single-tenant deployments:
node dist/cli.js --transport http --port 3000 --auth-token my-secret --postgres "postgres://..."
# Or via environment variable
export MCP_AUTH_TOKEN=my-secret
node dist/cli.js --transport http --port 3000 --postgres "postgres://..."
Clients must include Authorization: Bearer my-secret on all requests. /health and / are exempt. Unauthenticated requests receive 401 with WWW-Authenticate: Bearer headers per RFC 6750.
OAuth 2.1 (Enterprise)
Full OAuth 2.1 with RFC 9728/8414 compliance for production multi-tenant deployments:
node dist/cli.js \
--transport http \
--port 3000 \
--postgres "postgres://user:pass@localhost:5432/db" \
--oauth-enabled \
--oauth-issuer http://localhost:8080/realms/postgres-mcp \
--oauth-audience postgres-mcp-client
Additional flags:
--oauth-jwks-uri <url>(auto-discovered if omitted),--oauth-clock-tolerance <seconds>(default: 60).
OAuth Scopes
Access control is managed through OAuth scopes:
| Scope | Access Level |
|---|---|
read |
Read-only queries (SELECT, EXPLAIN) |
write |
Read + write operations |
admin |
Full administrative access |
full |
Grants all access |
db:{name} |
Access to specific database |
schema:{name} |
Access to specific schema |
table:{schema}:{table} |
Access to specific table |
RFC Compliance
This implementation follows:
- RFC 9728 — OAuth 2.1 Protected Resource Metadata
- RFC 8414 — OAuth 2.1 Authorization Server Metadata
- RFC 7591 — OAuth 2.1 Dynamic Client Registration
The server exposes metadata at /.well-known/oauth-protected-resource.
Note for Keycloak users: Add an Audience mapper to your client (Client → Client scopes → dedicated scope → Add mapper → Audience) to include the correct
audclaim in tokens.
[!NOTE] Per-tool scope enforcement: Scopes are enforced at the tool level — each tool group maps to a required scope (
read,write, oradmin). When OAuth is enabled, every tool invocation checks the calling token's scopes before execution. When OAuth is not configured, scope checks are skipped entirely.
[!WARNING] HTTP without authentication: When using
--transport httpwithout enabling OAuth or--auth-token, all clients have full unrestricted access. Always enable authentication for production HTTP deployments. See SECURITY.md for details.
Priority: When both
--auth-tokenand--oauth-enabledare set, OAuth 2.1 takes precedence. If neither is configured, the server warns and runs without authentication.
🔧 Configuration
Вопросы о PostgreSQL MCP
Как добавить PostgreSQL MCP в Claude Code?
Выполните claude mcp add postgres-mcp -- docker run -i --rm docker.io/writenotenow/postgres-mcp-enhanced:v1.2.0 в терминале. Добавьте --scope user, чтобы сервер был доступен во всех проектах.
Как добавить PostgreSQL MCP в Cursor?
Откройте ~/.cursor/mcp.json и добавьте сервер в mcpServers, используя конфигурацию Cursor из раздела установки выше.
Какие инструменты предоставляет PostgreSQL MCP?
Он предоставляет 25 инструментов, включая codemode, core, transactions, jsonb, text.
Как можно снизить расход токенов при выполнении сложных операций с базой данных?
Вы можете использовать Code Mode, который выполняет операции внутри безопасного изолята V8, что позволяет снизить нагрузку на AI на величину до 90%.
Как сервер обрабатывает ошибки базы данных для AI-агентов?
Он использует детерминированную обработку ошибок, чтобы перехватывать необработанные исключения SQL и преобразовывать их в четкие, практически применимые рекомендации, предотвращая галлюцинации AI.
Можно ли ограничить набор инструментов, доступных AI?
Да, вы можете использовать аргумент --tool-filter для динамической компиляции сервера с определенными группами инструментов или конкретными названиями инструментов.