🐳用 Docker + Cherry Studio 玩转 PostgreSQL MCP（实战笔记）这份笔记是给想在自己

在本地用 Docker + Cherry Studio 玩转 PostgreSQL MCP（实战笔记）

这份笔记是给想 在自己电脑上用 Cherry Studio + PostgreSQL MCP 做实验 的同学准备的，目标是：

不污染系统环境（全程用 Docker）
能用可视化工具管理数据库（pgAdmin）
能在 Cherry Studio 里正常调用 PostgreSQL MCP（执行 SQL、查表等）

0. 环境准备

已安装 Docker Desktop
已安装 Node.js（用于运行 npx @modelcontextprotocol/server-postgres）
已安装 Cherry Studio（CherryStudio）

1. 用 Docker Desktop 启动 PostgreSQL + pgAdmin

1.1 新建目录和 `docker-compose.yml`

随便找个目录，例如：

C:\postgres-mcp

在这个目录中新建文件：

docker-compose.yml

内容如下：

version: "3.9"
services:
  postgres:
    image: postgres:16
    container_name: postgres-mcp
    restart: always
    environment:
      POSTGRES_USER: mcpuser
      POSTGRES_PASSWORD: mcppassword
      POSTGRES_DB: mcpdb
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

  pgadmin:
    image: dpage/pgadmin4:latest
    container_name: pgadmin-mcp
    restart: always
    environment:
      PGADMIN_DEFAULT_EMAIL: admin@local.com
      PGADMIN_DEFAULT_PASSWORD: admin
    ports:
      - "5050:80"
    depends_on:
      - postgres

volumes:
  pgdata:

如需把数据固定到当前目录，可改为：

volumes:
  - ./pgdata:/var/lib/postgresql/data

1.2 启动数据库和管理界面

在该目录下打开终端（PowerShell / cmd）：

docker compose up -d

执行后会启动两个容器：

容器	说明	访问方式
`postgres-mcp`	PostgreSQL 数据库	`localhost:5432`
`pgadmin-mcp`	pgAdmin 可视化管理工具	浏览器访问 `http://localhost:5050`

1.3 使用 pgAdmin 连接数据库（可选但推荐）

浏览器打开：

http://localhost:5050

登录账号：

Email: admin@local.com
Password: admin

然后在 pgAdmin 里添加一个新服务器（New Server）：

Name: 随便写，例如 mcp-postgres
Connection 选项：
- Host: host.docker.internal（Cherry Studio / pgAdmin 在宿主机上时推荐）
- Port: 5432
- Username: mcpuser
- Password: mcppassword
- Database（可选）: mcpdb

注意：

在 宿主机 上访问 Docker 中的 PostgreSQL，用 localhost:5432 或 host.docker.internal:5432 都可以。

如果之后 Cherry Studio 跑在容器里，则更推荐 host.docker.internal。

2. 在 Cherry Studio 中配置 PostgreSQL MCP

这里以官方 Postgres MCP Server 为例：@modelcontextprotocol/server-postgres。

2.1 核心连接串（Connection String）

根据上面的 docker-compose，数据库连接串是：

postgresql://mcpuser:mcppassword@localhost:5432/mcpdb

如果你要显式用 host.docker.internal，则是：

postgresql://mcpuser:mcppassword@host.docker.internal:5432/mcpdb

2.2 Cherry Studio MCP JSON 配置示例

Cherry Studio 支持通过 JSON 配置 MCP Servers，形如：

{
  "mcpServers": {
    "名称": {
      "command": "...",
      "args": ["..."]
    }
  }
}

情况 A：Cherry Studio 跑在宿主机，使用 `localhost`

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://mcpuser:mcppassword@localhost:5432/mcpdb"
      ]
    }
  }
}

情况 B：Cherry Studio / 其他服务以容器形式跑，使用 `host.docker.internal`

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://mcpuser:mcppassword@host.docker.internal:5432/mcpdb"
      ]
    }
  }
}

提示：

postgres 是这个 MCP server 的名称，你可以改成 pg-mcp 等任意名字。

需要本机已安装 Node.js，且 npx 可用。

@modelcontextprotocol/server-postgres 会用后面的连接串直连你的 PostgreSQL。

3. 在 Cherry Studio 中验证 MCP 是否正常工作

打开 Cherry Studio → 设置 / MCP → MCP Servers
找到刚才配置的 postgres（或你自己起的名字）
确认状态是 Running / Active，没有明显报错
新建一个 Chat，选择支持 MCP 的模型

在对话中输入类似：

请帮我查看当前数据库里有哪些表

如果 MCP server 配置正确，Cherry Studio 会在后台发起 tool call，通过 PostgreSQL MCP 去读取数据库信息，并返回结果。

4. 建议的测试 SQL（可用 MCP 或 pgAdmin 执行）

为方便验证 MCP 是否真的能读写数据，可以先手动创建一张测试表并插入几条数据：

CREATE TABLE IF NOT EXISTS test_items (
    id SERIAL PRIMARY KEY,
    name TEXT,
    created_at TIMESTAMP DEFAULT NOW()
);

INSERT INTO test_items (name) VALUES
  ('hello mcp 1'),
  ('hello mcp 2');

SELECT * FROM test_items;

然后让 Cherry Studio 里的助手去查询：

请查询 test_items 这张表的所有数据，并按 created_at 倒序展示

如果能得到查询结果，并且和你在 pgAdmin 中看到的一致，就说明：

Docker 中 PostgreSQL 正常
MCP server 能连上数据库
Cherry Studio 能通过 MCP 调用 PostgreSQL

5. 常见问题与排查思路

5.1 MCP 服务状态不是 Running

检查本机是否安装了 Node.js

在命令行单独尝试：

npx -y @modelcontextprotocol/server-postgres postgresql://mcpuser:mcppassword@localhost:5432/mcpdb

看有没有明显报错（如连接失败、模块找不到等）

5.2 提示无法连接数据库

检查 postgresql://... 连接串中的：
- 用户名是否为 mcpuser
- 密码是否为 mcppassword
- host 是否为 localhost 或 host.docker.internal
- 端口是否为 5432
- 数据库名是否为 mcpdb
通过 pgAdmin / psql 用同样参数测试一遍

5.3 有连接但查询报权限错误

确认数据库用户 mcpuser 对目标表有 SELECT/INSERT/UPDATE/DELETE 权限
测试时尽量把表建在默认 public schema，避免 schema 名导致的访问问题

6. 关闭和清理

停止容器（但保留数据）：
```
docker compose down
```
如需删除数据卷（慎用，会清空数据库）：
```
docker compose down -v
```

7. 总结

整体流程可以概括为 3 步：

用 Docker 启动 PostgreSQL + pgAdmin
用标准 PostgreSQL 连接串配置 Cherry Studio 的 PostgreSQL MCP server
在 Cherry Studio 中用自然语言触发 SQL 查询，验证是否能成功调用 MCP

这样，你就拥有了一个 完全本地、可视化管理、可随时删库重来的 PostgreSQL + MCP 实验环境。

::contentReference[oaicite:0]{index=0}

🐳用 Docker + Cherry Studio 玩转 PostgreSQL MCP（实战笔记）