Name: PostgreSQL模型上下文协议服务器
Author: cnosuke

使用说明

mcp postgresql

PostgreSQL的模型上下文协议（MCP）服务器实现。

特性

列出数据库、模式和表
描述表结构（列、约束、索引、注释）
执行只读查询（SELECT）
使用RETURNING支持执行写查询（INSERT、UPDATE、DELETE）
创建和更改表格
支持PostgreSQL模式
安全操作的只读模式
通过DSN或单个参数连接
URL样式DSN支持(postgres://, postgresql://)
用于安全多数据库访问的连接预设（LLM永远看不到密码）
双重运输：stdio和流式HTTP（MCP规范2025-11-25）
HTTP传输的承载令牌身份验证和源验证
谷歌工作区OAuth 2.0 身份验证(安装指南)

安装

来源

git clone https://github.com/cnosuke/mcp-postgresql.git
cd mcp-postgresql
make

码头工人

docker pull cnosuke/mcp-postgresql

配置

配置文件（config.yml）

log: 'mcp-postgresql.log'  # Log file path (empty for no file logging; HTTP mode always outputs to console)
log_level: 'info'          # debug, info, warn, error

postgresql:
  host: 'localhost'
  user: 'postgres'
  password: ''
  port: 5432
  database: 'postgres'    # Default database
  schema: 'public'        # Default schema for search_path
  sslmode: 'disable'      # disable, allow, prefer, require, verify-ca, verify-full
  dsn: ''                 # Direct DSN (overrides above settings)
  read_only: false        # Enable read-only mode (disables write tools)

http:
  host: '127.0.0.1'        # Bind address (default: 127.0.0.1)
  port: 8080               # Listen port (default: 8080)
  endpoint: '/mcp'          # MCP endpoint path (default: /mcp)
  auth_token: ''            # Bearer token for authentication (empty = no auth)
  allowed_origins: []       # Allowed Origin headers (empty = allow all)

presets:
  production:
    host: 'prod-db.example.com'
    user: 'app_user'
    password: 'prod_password'
    port: 5432
    database: 'production_db'
    sslmode: 'require'
    read_only: true
  staging:
    dsn: 'postgres://staging_user:pass@staging-db:5432/staging_db'
    read_only: false

连接预设

预设允许管理多个数据库连接，而不会将密码暴露给LLM。每个预设在配置文件中定义了一个命名的连接配置文件。

预设字段： host, port, user, password, database, schema, sslmode, dsn, read_only, query_timeout

当 dsn 在预设中设置，它优先于单个字段
query_timeout: 0 回归全球 postgresql.query_timeout 价值
read_only: true 预设在运行时阻止所有写入操作
密码永远不会通过 list_preset 工具

环境变量

所有配置选项都可以通过环境变量覆盖：

变量	描述	默认值
`LOG_PATH`	日志文件路径	（空）
`LOG_LEVEL`	日志级别（调试、信息、警告、错误）	info
`POSTGRES_HOST`	PostgreSQL主机	本地主机
`POSTGRES_PORT`	PostgreSQL端口	5432
`POSTGRES_USER`	PostgreSQL用户	postgres
`POSTGRES_PASSWORD`	PostgreSQL密码	（空）
`POSTGRES_DATABASE`	数据库名称	postgres
`POSTGRES_SCHEMA`	默认架构	公共
`POSTGRES_SSLMODE`	SSL模式	禁用
`POSTGRES_DSN`	直接DSN连接字符串	（空）
`POSTGRES_READ_ONLY`	只读模式	false
`POSTGRES_QUERY_TIMEOUT`	查询超时（秒）	30
`HTTP_HOST`	HTTP服务器绑定地址	127.0.0.1
`HTTP_PORT`	HTTP服务器端口	8080
`HTTP_ENDPOINT`	MCP端点路径	/MCP
`HTTP_AUTH_TOKEN`	用于身份验证的承载令牌	（空）
`HTTP_ALLOWED_ORIGINS`	允许的Origin标头	（空）
`OAUTH_ENABLED`	启用OAuth身份验证	false
`OAUTH_ISSUER`	服务器的公共HTTPS URL	（空）
`OAUTH_SIGNING_KEY`	JWT签名密钥（>=32字节）	（空）
`OAUTH_TOKEN_EXPIRY`	令牌过期时间（秒）	3600
`GOOGLE_CLIENT_ID`	Google OAuth客户端ID	（空）
`GOOGLE_CLIENT_SECRET`	Google OAuth客户端机密	（空）
`GOOGLE_ALLOWED_DOMAINS`	允许的Google工作区域	（空）
`GOOGLE_ALLOWED_EMAILS`	允许的电子邮件地址	（空）

看 OAuth设置指南了解详情。

DSN格式

服务器支持两种DSN格式：

键值格式：

host=localhost port=5432 user=postgres password=secret dbname=mydb sslmode=disable

URL格式：

postgres://postgres:secret@localhost:5432/mydb?sslmode=disable
postgresql://postgres:secret@localhost:5432/mydb?sslmode=disable

用法

标准传输（默认）

# With default config
./bin/mcp-postgresql server

# With custom config
./bin/mcp-postgresql server --config=/path/to/config.yml

可流式HTTP传输

# Start HTTP server
./bin/mcp-postgresql http --config=/path/to/config.yml
# → http://127.0.0.1:8080/mcp
# → http://127.0.0.1:8080/health (no auth required)

HTTP传输支持：

原产地验证 （MCP规范必须要求，防止DNS重新绑定）
承载令牌身份验证 （定时安全比较）
谷歌工作区OAuth 2.0 （PKCE、CIMD、Google ID令牌验证）——请参阅 OAuth设置指南
健康检查端点 在 /health （无需身份验证）

码头工人

# Stdio transport
docker run -e POSTGRES_HOST=host.docker.internal \
           -e POSTGRES_USER=postgres \
           -e POSTGRES_PASSWORD=secret \
           -e POSTGRES_DATABASE=mydb \
           cnosuke/mcp-postgresql

# HTTP transport
docker run -p 8080:8080 \
           -e POSTGRES_HOST=host.docker.internal \
           -e POSTGRES_USER=postgres \
           -e POSTGRES_PASSWORD=secret \
           -e POSTGRES_DATABASE=mydb \
           -e HTTP_AUTH_TOKEN=your-secret-token \
           cnosuke/mcp-postgresql http --config=/app/config.yml

# HTTP transport with OAuth
docker run -p 8080:8080 \
           -e POSTGRES_HOST=host.docker.internal \
           -e POSTGRES_USER=postgres \
           -e POSTGRES_PASSWORD=secret \
           -e POSTGRES_DATABASE=mydb \
           -e OAUTH_ENABLED=true \
           -e OAUTH_ISSUER=https://mcp.example.com \
           -e OAUTH_SIGNING_KEY=your-pre-generated-signing-key \
           -e GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com \
           -e GOOGLE_CLIENT_SECRET=your-client-secret \
           -e GOOGLE_ALLOWED_DOMAINS=example.com \
           cnosuke/mcp-postgresql http --config=/app/config.yml

客户端配置

克劳德桌面（stdio）

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "postgresql": {
      "command": "/path/to/mcp-postgresql",
      "args": ["server", "--config=/path/to/config.yml"]
    }
  }
}

或者使用Docker：

{
  "mcpServers": {
    "postgresql": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "POSTGRES_HOST=host.docker.internal",
        "-e", "POSTGRES_USER=postgres",
        "-e", "POSTGRES_PASSWORD=secret",
        "-e", "POSTGRES_DATABASE=mydb",
        "cnosuke/mcp-postgresql"
      ]
    }
  }
}

克劳德代码（HTTP）

# Without authentication
claude mcp add mcp-postgresql --transport http http://localhost:8080/mcp

# With Bearer token authentication
claude mcp add mcp-postgresql --transport http http://localhost:8080/mcp \
  -H "Authorization: Bearer <token>"

可用工具

架构工具

工具	描述	只读模式
`list_preset`	列出已配置的连接预设	可用
`list_database`	列出所有数据库	可用
`list_schema`	列出所有架构（不包括系统架构）	可用
`list_table`	列出架构中的表	可用
`desc_table`	描述表格结构	可用
`create_table`	创建新表	已禁用
`alter_table`	更改现有表	已禁用

数据工具

工具	描述	只读模式
`read_query`	执行SELECT查询	可用
`write_query`	执行INSERT查询（支持返回）	已禁用
`update_query`	执行UPDATE查询（支持返回）	已禁用
`delete_query`	执行DELETE查询（支持返回）	已禁用

刀具参数

所有工具支持可选 dsn 和 preset 参数来覆盖配置的连接。这两个参数不能一起使用。

使用DSN：

{
  "name": "list_table",
  "arguments": {
    "schema": "my_schema",
    "dsn": "postgres://user:pass@host:5432/db"
  }
}

使用预设：

{
  "name": "read_query",
  "arguments": {
    "preset": "production",
    "query": "SELECT * FROM users LIMIT 10"
  }
}

PostgreSQL特定功能

架构支持

这 list_table 和 desc_table 工具支持a schema 参数：

{
  "name": "list_table",
  "arguments": {
    "schema": "my_schema"
  }
}

退货条款

写入操作(write_query, update_query, delete_query)支持PostgreSQL的RETURNING子句：

INSERT INTO users (name, email) VALUES ('John', 'john@example.com') RETURNING id, created_at;
UPDATE users SET status = 'active' WHERE id = 1 RETURNING *;
DELETE FROM users WHERE id = 1 RETURNING *;

表注释

PostgreSQL使用单独的 COMMENT ON 表和列注释语句：

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL
);

COMMENT ON TABLE users IS 'User account information';
COMMENT ON COLUMN users.name IS 'Full name of the user';

发展

构建

make

测试

make test

Docker构建

make docker-build

许可证

MIT许可证

作者

@cnosuke

使用说明

mcp postgresql

特性

安装

来源

码头工人

配置

配置文件（config.yml）

连接预设

环境变量

DSN格式

用法

标准传输（默认）

可流式HTTP传输

码头工人

客户端配置

克劳德桌面（stdio）

克劳德代码（HTTP）

可用工具

架构工具

数据工具

刀具参数

PostgreSQL特定功能

架构支持

退货条款

表注释

发展

构建

测试

Docker构建

许可证

作者

相关 MCP

网页内容抓取服务器

模型上下文协议服务器

MySQL数据库管理工具

结构化推理工具

MongoDB 数据库 MCP 服务器

AutoRAG 检索 MCP 服务