使用说明

项目简介

本项目 'postgres-mcp' 是一个实现了 Model Context Protocol (MCP) 协议的服务器，专门用于提供对 PostgreSQL 数据库的只读访问能力。它允许大型语言模型 (LLM) 通过标准的 MCP 接口，安全地获取 PostgreSQL 数据库的结构信息（Schema）并执行只读的 SQL 查询。

主要功能点

资源 (Resources):
- 表结构信息 (Table Schemas): 服务器能够自动发现 PostgreSQL 数据库中的所有表，并为每张表提供 JSON 格式的结构信息。这些信息包括表的列名和数据类型，LLM 可以利用这些信息来理解数据库的结构。资源URI格式为 'postgres://<host>/<table>/schema'。
工具 (Tools):
- query (SQL查询工具): 提供一个名为 'query' 的工具，允许 LLM 执行只读的 SQL 查询。该工具接收 SQL 查询语句作为输入，并在只读事务中执行查询，返回查询结果的 JSON 格式数据。

安装步骤

前提条件:

确保已安装 Docker 或 Node.js 和 npm (或 npx)。
PostgreSQL 数据库服务已运行，并拥有可连接的数据库。

方法一：使用 Docker 运行

构建 Docker 镜像 (可选，如果使用预构建镜像可跳过): 打开终端，进入仓库根目录（包含 'Dockerfile' 的目录），执行以下命令构建 Docker 镜像：
```
docker build -t mcp/postgres -f src/postgres/Dockerfile .
```
运行 Docker 容器: 使用以下命令运行 Docker 容器，将 '<PostgreSQL连接URL>' 替换为你的 PostgreSQL 数据库连接 URL。
```
docker run -i --rm mcp/postgres "<PostgreSQL连接URL>"
```
例如，如果你的 PostgreSQL 服务运行在 'localhost:5432'，数据库名为 'mydb'，则命令可能如下：
```
docker run -i --rm mcp/postgres "postgresql://localhost:5432/mydb"
```
注意: 如果你的 MCP 客户端（如 Claude Desktop）和 PostgreSQL 服务都运行在同一台机器上，但客户端在 Docker 容器内，而 PostgreSQL 服务在宿主机上，则连接 URL 中的 'localhost' 或 '127.0.0.1' 指的是 Docker 容器内部的网络。你需要使用 'host.docker.internal' (在 macOS 和较新版本的 Windows 上) 或宿主机的 IP 地址来连接到宿主机上的 PostgreSQL 服务。

方法二：使用 NPX 运行 (需要 Node.js 和 npm)

安装依赖 (如果尚未安装): 确保已安装 Node.js 和 npm。

运行 NPX 命令: 使用以下命令直接运行，将 '<PostgreSQL连接URL>' 替换为你的 PostgreSQL 数据库连接 URL。

npx -y @modelcontextprotocol/server-postgres "<PostgreSQL连接URL>"

例如：

npx -y @modelcontextprotocol/server-postgres "postgresql://localhost/mydb"

服务器配置 (MCP客户端配置)

要将此 MCP 服务器配置到 MCP 客户端（例如 Claude Desktop），你需要在客户端的 MCP 服务器配置中添加以下 JSON 配置。

Docker 方式配置：

{
  "mcpServers": {
    "postgres": {  // 服务器名称，可以自定义
      "command": "docker", // 启动命令，这里使用 docker
      "args": [  // 启动参数
        "run",
        "-i",
        "--rm",
        "mcp/postgres", // Docker 镜像名称，与构建或拉取的镜像名一致
        "postgresql://host.docker.internal:5432/mydb" // PostgreSQL 连接 URL，根据实际情况修改
        // 注意：host.docker.internal 用于从 Docker 容器内部访问宿主机网络上的服务
      ]
    }
  }
}

NPX 方式配置：

{
  "mcpServers": {
    "postgres": {  // 服务器名称，可以自定义
      "command": "npx", // 启动命令，这里使用 npx
      "args": [  // 启动参数
        "-y",
        "@modelcontextprotocol/server-postgres", // 使用的 npm 包名
        "postgresql://localhost/mydb" // PostgreSQL 连接 URL，根据实际情况修改
      ]
    }
  }
}

配置说明:

'"postgres"': 是你为这个 MCP 服务器定义的名称，在客户端中用于引用此服务器。你可以自定义这个名称。
'"command"': 指定启动 MCP 服务器的命令。Docker 方式使用 '"docker"'，NPX 方式使用 '"npx"'。
'"args"': 是一个字符串数组，包含了启动命令的参数。
- Docker 方式的参数包括 'docker run -i --rm mcp/postgres' 以及 PostgreSQL 连接 URL。
- NPX 方式的参数包括 '-y @modelcontextprotocol/server-postgres' 以及 PostgreSQL 连接 URL。
'"postgresql://...' : 请务必将连接 URL 替换为你实际的 PostgreSQL 数据库连接信息，包括主机地址、端口、数据库名，以及可能的用户名和密码。例如：'postgresql://user:password@host:port/database'。

基本使用方法

启动 MCP 服务器: 按照上述 Docker 或 NPX 方式启动 'postgres-mcp' 服务器，并确保服务器成功运行，没有报错信息。
配置 MCP 客户端: 将上述 JSON 配置添加到你的 MCP 客户端（如 Claude Desktop）的配置文件中，并确保服务器名称与配置中的名称一致（例如 '"postgres"'）。
在 MCP 客户端中使用: 在 LLM 客户端中，你现在应该能够：
- 列出资源: 客户端可以请求列出 'postgres-mcp' 服务器提供的资源，你将看到以表名命名的表结构资源。
- 读取资源: 客户端可以请求读取特定表的结构资源，例如使用 URI 'postgres://<host>/<table>/schema'，服务器将返回该表的 JSON Schema 信息。
- 调用工具: 客户端可以调用名为 'query' 的工具，并提供 SQL 查询语句作为参数。服务器将执行查询并返回结果。

示例使用场景：

LLM 客户端可以先列出资源，获取数据库中的表名，然后读取感兴趣的表的 Schema 信息，理解表的结构。之后，LLM 可以使用 'query' 工具，根据用户指令生成 SQL 查询，并发送给 'postgres-mcp' 服务器执行，从而获取数据库中的数据，并将结果用于生成更丰富的回答或执行更复杂的操作。

关键词