使用说明
PostgreSQL MCP AI浏览器
v1.2.0版本 |MCP SDK 1.26·psycopg 3·Streamlit
PostgreSQL数据库 MCP（模型上下文协议） 连接到，
与AI对话，用自然语言浏览和可视化数据的项目。
🚀 主要功能
| 功能 | 说明 |
|---|---|
| 自然语言→SQL转换 | 无需复杂的SQL语法，通过问题查询数据 |
| MCP协议支持 | 与Claude Desktop（stdio）和其他MCP客户端（SSE）配合使用 |
| 流线型Web UI | 聊天界面+自动生成Plotly图表 |
| 实战演示数据 | 包括韩国式人事管理数据集自动生成脚本 |
🛠️ 安装和设置
1.必备条件
- Python 3.10或更高版本
- PostgreSQL数据库（本地或Docker）
- 诗歌 （包管理器）
2.安装
# 의존성 설치
poetry install
3.首选参数（.env）
在项目根目录中 .env 创建文件并输入数据库信息。
# PostgreSQL 접속 정보
DB_HOST=localhost
DB_PORT=5432
DB_NAME=postgres
DB_USER=postgres
DB_PASSWORD=your_password
# (선택) AI API 키 — Streamlit 웹 UI에서 자연어→SQL 변환 시 필요
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
🏃♂️ 执行方法
1.初始化数据库（生成演示数据）
实习用 인사관리 创建表并填充约50名虚拟员工的信息。
poetry run python scripts/setup_demo_data.py
2-A.Claude Desktop集成（stdio模式，基本）
Claude Desktop的配置文件 %APPDATA%\Claude\claude_desktop_config.json 向中添加以下内容：
{
"mcpServers": {
"postgresql": {
"command": "<프로젝트경로>\\.venv\\Scripts\\python.exe",
"args": ["-m", "src.server"],
"env": {
"PYTHONPATH": "<프로젝트경로>"
}
}
}
}
设置后Claude Desktop 重新开始MCP服务器将自动连接。
2-B.Streamlit Web UI（SSE模式）
分别运行SSE后端服务器和Streamlit前端。
# 터미널 1: MCP 서버 (SSE 모드)
poetry run python -m src.server --sse
# 터미널 2: Streamlit 앱
poetry run streamlit run src/streamlit_app.py
🧪 测试查询示例
- “开发团队的平均年薪是多少？”
- “在工作3年以上的职员中，给我看工资前5名”
- “请把各部门的男女性别比例画成饼图。”
- “同时展示各部门人数TOP5和平均工龄”
- “今年入职的新职员名单”
更多示例包括 query.md 请参考。
📁 项目结构
PostgreSQL_MCP/
├── src/ # 핵심 패키지 (서버 + 설정 + 웹 UI)
│ ├── __init__.py # 패키지 메타 (버전 정보)
│ ├── server.py # MCP 서버 핵심 로직 (stdio + SSE 전송)
│ ├── config.py # 통합 설정 (DB, MCP, AI 프롬프트 등)
│ └── streamlit_app.py # Streamlit 웹 UI (채팅 + 차트)
├── scripts/
│ └── setup_demo_data.py # 데모 데이터(인사관리) 생성 스크립트
├── docs/
│ └── ARCHITECTURE.md # 시스템 아키텍처 문서
├── query.md # 추천 자연어 쿼리 예시 모음
├── pyproject.toml # Poetry 의존성 관리
├── claude_desktop_config.json # Claude Desktop 설정 예시
└── archive/ # 이전 버전 / 디버깅용 파일 보관