PostgreSQL架构MCP服务器
一个模型上下文协议（MCP）服务器，它对PostgreSQL数据库架构进行索引，并允许大型语言模型（LLMs）通过自然语言查询架构信息并执行只读SQL查询。
概述
这个MCP服务器提供：
- PostgreSQL数据库的模式元数据索引
- 同时支持多个PostgreSQL数据库
- 使用可配置间隔的背景模式索引
- 与MCP兼容客户端（Kilo Code、Cursor、Claude Desktop）无缝集成
- 带有内置安全控制的只读查询执行
- 用于数据库探索的自然语言接口
为什么选择MCP？
模型上下文协议提供：
- 无需自定义用户界面/接口
- 与人工智能开发工具的直接集成
- 大型语言模型（LLM）工具调用的标准协议
- 原生支持异步操作
建筑
┌─────────────────────────────────────────────────────────────┐
│ LLM Client (MCP Compatible) │
│ "Show me all tables in the database" │
└─────────────────────────┬───────────────────────────────────┘
│ MCP Protocol
┌─────────────────────────▼───────────────────────────────────┐
│ MCP Server │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Tools: list_databases, get_schema, execute_query... │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────┬───────────────────────────────────┘
│
┌─────────────────┼─────────────────┐
│ │ │
┌───────▼────────┐ ┌─────▼──────┐ ┌────────▼─────────┐
│ Schema Indexer │ │Schema Cache│ │ Metadata Store │
│ (Worker) │ │ (Memory) │ │ (SQLite) │
└───────┬────────┘ └────────────┘ └──────────────────┘
│
│ Read-Only Schema Queries
│
┌───────▼─────────────────────────────────────────────────┐
│ PostgreSQL Databases (information_schema access) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ DB 1 │ │ DB 2 │ │ DB N │ │
│ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────┘快速入门
先决条件
- Node.js 20多个版本（或：Node.js 20+ 版本）
- PostgreSQL 数据库（一个或多个）
- 兼容MCP的客户端（Kilo Code、Cursor或Claude Desktop）
安装
# Clone the repository
git clone
cd postgres-schema-mcp
# Install dependencies
npm install
# Configure environment variables
cp .env.example .env
# Edit .env and add your PostgreSQL credentials
# Create database configuration
cp config/databases.example.json config/databases.json
# Edit config/databases.json with your database details
# Build the project
npm run buildPostgreSQL 只读用户设置
为了安全起见，请创建一个专用的只读用户：
-- Create read-only user
CREATE USER readonly_user WITH PASSWORD 'secure_password';
-- Grant connection to database
GRANT CONNECT ON DATABASE your_database TO readonly_user;
-- Grant schema access
GRANT USAGE ON SCHEMA public TO readonly_user;
-- Grant access to information_schema and pg_catalog only
GRANT SELECT ON ALL TABLES IN SCHEMA information_schema TO readonly_user;
GRANT SELECT ON ALL TABLES IN SCHEMA pg_catalog TO readonly_user;
-- No direct data table access required for schema indexingMCP客户端配置
将服务器添加到您的MCP客户端配置中：
千位分隔符代码/光标：
位置：
- macOS/Linux：
~/.config/Code/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json - Windows：
%APPDATA%\Code\User\globalStorage\kilocode.kilo-code\settings\mcp_settings.json
配置：
{
"mcpServers": {
"postgres-schema": {
"command": "node",
"args": ["/absolute/path/to/postgres-schema-mcp/dist/index.js"],
"env": {
"PG_SCHEMA_PASSWORD": "your_schema_password",
"PG_QUERY_PASSWORD": "your_query_password"
}
}
}
}运行服务器
# Development mode with auto-reload
npm run dev
# Production mode
npm start配置
数据库配置
创建 config/databases.json 来自示例：
{
"databases": [
{
"id": "production-db",
"name": "Production Database",
"connection": {
"host": "localhost",
"port": 5432,
"database": "myapp",
"schemaUser": "readonly_schema_user",
"schemaPassword": "${PG_SCHEMA_PASSWORD}",
"queryUser": "readonly_query_user",
"queryPassword": "${PG_QUERY_PASSWORD}",
"ssl": false
},
"indexing": {
"enabled": true,
"interval": "1h",
"schemas": ["public"],
"excludeTables": ["migrations", "schema_version"]
},
"queryExecution": {
"enabled": true,
"maxLimit": 1000,
"defaultLimit": 100,
"timeout": 30000,
"rateLimit": {
"maxQueries": 100,
"windowMs": 60000,
"maxConcurrent": 5
}
}
}
],
"worker": {
"parallelism": 3,
"retryAttempts": 3
}
}环境变量
创建 .env 来自 .env.example：
# PostgreSQL Credentials
PG_SCHEMA_PASSWORD=your_schema_readonly_password
PG_QUERY_PASSWORD=your_query_readonly_password
# Metadata DB Path
METADATA_DB_PATH=./data/metadata.db
# Logging
LOG_LEVEL=info可用的MCP工具
“ask_monkey”可以翻译为“问猴子”或根据上下文意译为“向猴子提问”等，具体翻译取决于该短语在特定语境中的含义和用途。如果“ask_monkey”是一个特定的应用程序、网站或功能的名称，那么可能需要一个更具体的翻译或保留原名。但基于直接翻译，上述翻译是较为通用的表达
由大型语言模型（LLM）推理驱动的自然语言数据库助手。
要求：
- 目前需要 LM 代理 使用 GitHub Copilot 进行编程
- 在（某处）进行配置
.env：
AGENT_ENABLED=true
AGENT_LM_PROXY_URL=http://localhost:4000
AGENT_MODEL=gpt-4o输入：
{
"question": "Show me all tables in the database",
"databaseId": "production-db",
"detailed": false
}用自然语言提问——Monkey 为您构建并执行最优 SQL 查询。
注： Monkey代理是一个自主数据库助手，它：
- 分析你的自然语言问题
- 自动读取数据库模式
- 构建并执行优化的SQL查询
- 返回包含推理步骤的格式化结果
有关LM代理设置的更多详细信息，请参阅 VSCode LM 代理文档。
CLI 工具
交互式添加数据库
npm run add-db交互式向导用于添加新数据库：
- 连接详情
- SSL配置
- 模式选择
- 查询限制
- 连接测试
发现模式（或架构）
npm run discover在配置的数据库中探索模式。
查看日志
npm run logs查看服务器日志以进行调试和监控。
项目结构
postgres-schema-mcp/
├── src/
│ ├── index.ts # Entry point
│ ├── mcp/
│ │ ├── server.ts # MCP server implementation
│ │ └── tools/ # Tool implementations
│ ├── agent/
│ │ └── monkey.ts # Natural language query agent
│ ├── db/
│ │ └── metadata.ts # SQLite metadata store
│ ├── services/
│ │ ├── schemaExtractor.ts
│ │ ├── queryExecutor.ts
│ │ └── queryValidator.ts
│ └── types/
│ └── index.ts
├── config/
│ └── databases.json # Database configurations
├── data/
│ └── metadata.db # Schema cache
└── bin/
└── monkey.cjs # CLI wrapper发展
脚本
# Development
npm run dev # Start with auto-reload
npm run build # Build TypeScript
npm start # Start production server
# Database Management
npm run add-db # Add new database
npm run discover # Discover schemas
# Utilities
npm run logs # View logs
npm run help # Show all commands测试
# Run all tests
npm test
# Run specific test suites
npm run test:unit
npm run test:integration安全
最佳实践
- 只读用户始终使用专用的只读 PostgreSQL 用户
- 环境变量永远不要将凭据提交到版本控制系统中
- SSL/TLS为生产数据库使用SSL
- 最小特权原则仅授予必要的模式访问权限
- 速率限制配置适当的查询速率限制
不存储的内容
- 表中无数据行
- 没有列内容
- 无敏感信息
- 仅模式元数据（结构）
查询执行安全性
- 仅允许使用SELECT查询
- 自动执行限制（或：自动限制执行）
- 查询超时保护
- 每个数据库的速率限制
- 只读事务模式
- 查询验证和清理
演出
优化
- 内存中模式缓存
- 增量式模式更新
- 并行数据库索引
- 连接池
- 用于快速元数据查询的SQLite索引
典型的索引时间
- 小型数据库（\= 20
Reinstall dependencies
npm install
Check logs
npm run logs
### 数据库连接问题
Test connection manually
psql -h localhost -U readonly_user -d your_database
Check user permissions
\du readonly_user
### MCP 客户端无法检测到服务器
1. 在MCP配置中验证绝对路径
1. 重建项目： `npm run build`
1. 完全重启MCP客户端
1. 检查客户端日志中的错误
## 贡献；做出贡献
欢迎投稿！请：
1. 为仓库创建分支（或：克隆仓库）
1. 创建一个特性分支（`git checkout -b feature/amazing-feature`)
1. 提交您的更改（`git commit -m 'Add amazing feature'`）
1. 推送到分支（`git push origin feature/amazing-feature`）
1. 提交一个拉取请求（或合并请求）
## 许可证
MIT 许可证 - 详见 LICENSE 文件
## 功劳/学分
- Anthropic的模型上下文协议
- PostgreSQL——世界上最先进的开源数据库
- Node.js 运行时
## 支持
对于问题或疑问：
- 在GitHub上打开一个议题
- 检查现有问题和文档
- 查看故障排除部分
______________________________________________________________________
通过模型上下文协议，构建以实现更好的大型语言模型（LLM）与数据库集成。