Read Only Local Postgres MCP Server

🚀 PostgreSQL MCP Server

这是一个模型上下文协议（MCP）服务器，它使Claude Desktop能够通过自然语言查询与PostgreSQL数据库进行交互。

🚀 快速开始

针对Claude Code用户（推荐 - 最简单的方法）

claude mcp add postgres -s user -- npx -y @hovecapital/read-only-postgres-mcp-server

然后设置数据库环境变量：

export DB_HOST=localhost
export DB_PORT=5432
export DB_DATABASE=your_database_name
export DB_USERNAME=your_username
export DB_PASSWORD=your_password

完成！ 重启Claude Code并询问：“我的数据库中有哪些表？”

针对Claude Desktop用户（手动配置）

1. 打开配置文件：

# macOS
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
notepad %APPDATA%\Claude\claude_desktop_config.json

2. 添加以下配置：

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@hovecapital/read-only-postgres-mcp-server"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_DATABASE": "your_database_name",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

3. 保存，重启Claude Desktop并进行测试！

✨ 主要特性

• 通过Claude Desktop或Claude Code执行只读SQL查询。
• 动态数据库连接 - 在运行时连接到任何PostgreSQL数据库。
• 内置查询验证安全机制（仅允许SELECT语句）。
• 易于与Claude Desktop和Claude Code集成。
• 查询结果采用JSON格式。
• 支持基于环境的默认配置，并可在运行时覆盖。

📦 安装指南

选项1：从MCP注册表安装（推荐）

此服务器已发布在模型上下文协议注册表中，名称为capital.hove/read-only-local-postgres-mcp-server。

方法A：Claude Code CLI（最简单！）

claude mcp add postgres -s user -- npx -y @hovecapital/read-only-postgres-mcp-server

然后使用环境变量配置数据库凭证。重启Claude Code即可完成安装！ 优点：

• 一键安装。
• 无需手动编辑JSON。
• 自动配置。

方法B：手动JSON配置

对于Claude Desktop： 编辑~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或%APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@hovecapital/read-only-postgres-mcp-server"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_DATABASE": "your_database_name",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

对于Claude Code： 编辑~/.config/claude-code/settings.json（macOS/Linux）或%APPDATA%\claude-code\settings.json（Windows）：

{
  "mcp": {
    "servers": {
      "postgres": {
        "command": "npx",
        "args": ["-y", "@hovecapital/read-only-postgres-mcp-server"],
        "env": {
          "DB_HOST": "localhost",
          "DB_PORT": "5432",
          "DB_DATABASE": "your_database_name",
          "DB_USERNAME": "your_username",
          "DB_PASSWORD": "your_password"
        }
      }
    }
  }
}

选项2：从npm安装

npm install -g @hovecapital/read-only-postgres-mcp-server

选项3：使用Claude Code安装

如果你使用的是Claude Code，可以轻松安装此MCP服务器：

# 克隆仓库
git clone https://github.com/hovecapital/read-only-local-postgres-mcp-server.git
cd read-only-local-postgres-mcp-server

# 安装依赖并构建
npm install
npm run build

然后通过添加到MCP设置来配置Claude Code。

选项4：手动安装

1. 克隆或下载

将仓库保存到系统上的一个目录中：

mkdir ~/mcp-servers/postgres
cd ~/mcp-servers/postgres
git clone https://github.com/hovecapital/read-only-local-postgres-mcp-server.git .

2. 安装依赖

npm install
npm run build

🔧 配置

注意： 如果你通过选项1（使用npx从MCP注册表安装）进行安装，那么你已经完成了所有配置！本节适用于选择选项2、3或4（通过npm或手动安装）的用户。

Claude Code配置

如果你手动安装并使用Claude Code，将PostgreSQL服务器添加到MCP设置中：

1. 打开Claude Code设置（通常在macOS/Linux上为~/.config/claude-code/settings.json，在Windows上为%APPDATA%\claude-code\settings.json）。
2. 添加PostgreSQL MCP服务器配置：

{
  "mcp": {
    "servers": {
      "postgres": {
        "command": "node",
        "args": ["/absolute/path/to/read-only-local-postgres-mcp-server/dist/index.js"],
        "env": {
          "DB_HOST": "localhost",
          "DB_PORT": "5432",
          "DB_DATABASE": "your_database_name",
          "DB_USERNAME": "your_username",
          "DB_PASSWORD": "your_password"
        }
      }
    }
  }
}

3. 重启Claude Code以使更改生效。

Claude Desktop配置

如果你手动安装并使用Claude Desktop，打开Claude Desktop配置文件： macOS：

~/Library/Application Support/Claude/claude_desktop_config.json

Windows：

%APPDATA%\Claude\claude_desktop_config.json

添加PostgreSQL服务器配置：

{
  "mcpServers": {
    "postgres": {
      "command": "node",
      "args": ["/absolute/path/to/read-only-local-postgres-mcp-server/dist/index.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_DATABASE": "your_database_name",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password"
      }
    }
  }
}

使用mise管理Node.js

如果你使用mise进行Node.js版本管理，请确保在配置中使用Node.js可执行文件的完整路径。

环境变量

💻 使用示例

工具介绍

此MCP服务器提供了三个工具，Claude可以使用这些工具与PostgreSQL数据库进行交互。

connect

使用连接字符串连接到PostgreSQL数据库。连接将持续到后续查询，直到更改或断开连接。 参数：

连接字符串格式：

postgres://username:password@host:port/database?sslmode=require
postgresql://username:password@host:port/database

支持的SSL模式：

• sslmode=require - 需要SSL（推荐用于远程连接）
• sslmode=verify-full - 需要SSL并进行证书验证
• 无sslmode参数 - 不使用SSL（用于本地连接）

示例用法（自然语言）：

"Connect to postgres://myuser:mypass@db.example.com:5432/production"
"Connect to this database: postgres://admin:secret@localhost/analytics"

响应：

{
  "status": "connected",
  "host": "db.example.com",
  "port": 5432,
  "database": "production",
  "user": "myuser",
  "ssl": true
}

disconnect

从当前运行时数据库断开连接，并恢复到默认环境配置的连接。 参数： 无 示例用法（自然语言）：

"Disconnect from the current database"
"Go back to the default database"

响应：

{
  "status": "disconnected",
  "message": "Reverted to default environment connection",
  "host": "localhost",
  "database": "postgres"
}

query

针对当前连接的数据库运行只读SQL查询。可选择为单个查询覆盖连接。 参数：

示例用法（自然语言）：

"Show me all tables in the database"
"SELECT * FROM users LIMIT 10"
"Run this query on postgres://other:pass@host/db: SELECT count(*) FROM orders"

响应：

[
  { "id": 1, "name": "Alice", "email": "alice@example.com" },
  { "id": 2, "name": "Bob", "email": "bob@example.com" }
]

大语言模型工具参考

使用此MCP服务器时，Claude可以：

1. 查询默认数据库（通过环境变量配置）：

用户："What tables are in my database?"
Claude：[使用查询工具执行SQL: "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'"]

2. 动态连接到不同的数据库：

用户："Connect to postgres://user:pass@newhost/newdb and show me the users table"
Claude：[先使用连接工具，然后使用查询工具]

3. 对不同数据库进行一次性查询（不切换活动连接）：

用户："How many records are in the orders table on postgres://user:pass@analytics/warehouse?"
Claude：[使用带有connectionString参数的查询工具]

4. 恢复到默认连接：

用户："Go back to my local database"
Claude：[使用断开连接工具]

实际使用示例

1. 更新配置后重启Claude Desktop/Code。
2. 开始与Claude聊天，询问有关数据库的问题。

基本查询（使用默认/活动连接）：

"Show me all tables in my database"
"What's the structure of the users table?"
"Get the first 10 records from the products table"
"How many orders were placed last month?"
"Show me users with email addresses ending in @gmail.com"

动态连接示例：

"Connect to postgres://analyst:password@analytics.example.com:5432/warehouse"
"Now show me all the tables"
"What's the total revenue in the sales table?"
"Disconnect and go back to my local database"

对不同数据库进行一次性查询：

"Run SELECT count(*) FROM users on postgres://admin:secret@prod.example.com/app"
"Check the orders table on my staging database: postgres://dev:dev@staging/app"

Claude将自动将你的自然语言请求转换为适当的SQL查询，并在你的数据库上执行。

🔒 安全特性

只读操作

服务器对所有连接（包括环境配置和运行时动态连接）强制执行只读访问。以下操作将被阻止：

• INSERT - 添加新记录
• UPDATE - 修改现有记录
• DELETE - 删除记录
• DROP - 删除表/数据库
• ALTER - 修改表结构
• CREATE - 创建新表/数据库
• TRUNCATE - 删除表中的所有记录
• GRANT - 修改权限
• REVOKE - 撤销权限

动态连接安全

使用connect工具或connectionString参数时：

• 仍然强制执行只读操作 - 无论连接来源如何，所有查询都会进行验证。
• 不记录凭证 - 包含密码的连接字符串不会写入日志。
• 响应经过清理 - connect工具的响应中不包含密码。
• 基于会话 - 运行时连接仅在当前MCP会话中持续。

推荐的数据库设置

为增强安全性，为MCP服务器创建一个专用的只读用户：

-- 创建只读用户
CREATE USER claude_readonly WITH PASSWORD 'secure_password';

-- 仅授予特定模式的SELECT权限
GRANT USAGE ON SCHEMA public TO claude_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_readonly;

-- （可选）为未来的表授予权限
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO claude_readonly;

🛠️ 故障排除

连接问题

1. 验证PostgreSQL是否正在运行：检查PostgreSQL服务器是否处于活动状态。
2. 检查凭证：确保用户名/密码正确。
3. 网络连接：确认Claude Desktop可以访问你的PostgreSQL服务器。

配置问题

1. 需要重启：配置更改后，始终重启Claude Desktop。
2. 路径准确性：确保dist/index.js的绝对路径正确。
3. JSON语法：验证claude_desktop_config.json的格式。

调试模式

要查看服务器日志，你可以手动运行服务器：

node dist/index.js

📂 文件结构

~/mcp-servers/postgres/
├── src/
│   └── index.ts
├── dist/
│   ├── index.js
│   └── index.d.ts
├── package.json
├── tsconfig.json
└── node_modules/

📦 依赖项

• @modelcontextprotocol/sdk：MCP协议实现
• pg：用于Node.js的PostgreSQL客户端

🤝 贡献

欢迎提交问题和改进请求！

📄 许可证

本项目是开源的，采用MIT许可证。

💪 支持

如果你遇到问题：

1. 查看上面的故障排除部分。
2. 独立验证你的PostgreSQL连接。
3. 确保Claude Desktop已更新到最新版本。
4. 查看Claude Desktop MCP文档。

注意：此服务器是为开发和分析目的而设计的。对于生产环境使用，请考虑额外的安全措施和监控。