[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"tool-subnetmarco--pgmcp":3,"similar-subnetmarco--pgmcp":108},{"id":4,"github_repo":5,"name":6,"description_en":7,"description_zh":8,"ai_summary_zh":8,"readme_en":9,"readme_zh":10,"quickstart_zh":11,"use_case_zh":12,"hero_image_url":13,"owner_login":14,"owner_name":15,"owner_avatar_url":16,"owner_bio":17,"owner_company":18,"owner_location":19,"owner_email":20,"owner_twitter":14,"owner_website":21,"owner_url":22,"languages":23,"stars":36,"forks":37,"last_commit_at":38,"license":39,"difficulty_score":40,"env_os":41,"env_gpu":42,"env_ram":43,"env_deps":44,"category_tags":51,"github_topics":56,"view_count":40,"oss_zip_url":69,"oss_zip_packed_at":69,"status":70,"created_at":71,"updated_at":72,"faqs":73,"releases":102},4458,"subnetmarco\u002Fpgmcp","pgmcp","An MCP server to query any Postgres database in natural language.","pgmcp 是一款基于模型上下文协议（MCP）的开源服务器，旨在让 AI 助手能够直接用自然语言查询任意 PostgreSQL 数据库。用户只需像日常对话一样提问，例如“哪位客户下单最多？”，pgmcp 即可自动将其转化为安全的 SQL 查询并返回结构化结果，无需编写任何代码。\n\n它主要解决了非技术人员访问数据库门槛高、以及开发者在集成 AI 与数据库时需重复构建安全层的问题。通过 pgmcp，业务人员、数据分析师或产品经理可以直接与数据库对话获取洞察，而开发者则能快速为 Cursor、Claude Desktop 或 VS Code 等工具添加数据库交互能力，大幅降低集成成本。\n\n该工具特别适合希望利用 AI 提升数据查询效率的开发团队、需要灵活获取数据的研究人员，以及不熟悉 SQL 但需频繁查阅数据的业务用户。其核心技术亮点包括：严格的只读访问机制确保数据绝对安全；支持自动流式传输以处理海量数据；内置智能错误恢复与大小写敏感表名支持；兼容各类现有数据库架构，无需修改表结构即可立即使用。此外，它还支持多种输出格式及全文搜索功能，是连接人工智能与企业数据资产的轻量级桥梁。","[![ci](https:\u002F\u002Fgithub.com\u002Fsubnetmarco\u002Fpgmcp\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fsubnetmarco\u002Fpgmcp\u002Factions\u002Fworkflows\u002Fci.yml)\n[![Go Report Card](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fsubnetmarco_pgmcp_readme_2b4a70945b89.png)](https:\u002F\u002Fgoreportcard.com\u002Freport\u002Fgithub.com\u002Fsubnetmarco\u002Fpgmcp)\n[![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-Apache%202.0-blue.svg)](https:\u002F\u002Fopensource.org\u002Flicenses\u002FApache-2.0)\n\n# PGMCP - PostgreSQL Model Context Protocol Server\n\nPGMCP connects AI assistants to **any PostgreSQL database** through natural language queries. Ask questions in plain English and get structured SQL results with automatic streaming and robust error handling.\n\n**Works with**: Cursor, Claude Desktop, VS Code extensions, and any [MCP-compatible client](https:\u002F\u002Fmodelcontextprotocol.io\u002F)\n\n## Quick Start\n\nPGMCP connects to **your existing PostgreSQL database** and makes it accessible to AI assistants through natural language queries.\n\n### Prerequisites\n- PostgreSQL database (existing database with your schema)\n- OpenAI API key (optional, for AI-powered SQL generation)\n\n### Basic Usage\n\n```bash\n# Set up environment variables\nexport DATABASE_URL=\"postgres:\u002F\u002Fuser:password@localhost:5432\u002Fyour-existing-db\"\nexport OPENAI_API_KEY=\"your-api-key\"  # Optional\n\n# Run server (using pre-compiled binary)\n.\u002Fpgmcp-server\n\n# Test with client in another terminal\n.\u002Fpgmcp-client -ask \"What tables do I have?\" -format table\n.\u002Fpgmcp-client -ask \"Who is the customer that has placed the most orders?\" -format table\n.\u002Fpgmcp-client -search \"john\" -format table\n```\n\nHere is how it works:\n\n```\n👤 User \u002F AI Assistant\n         │\n         │ \"Who are the top customers?\"\n         ▼\n┌─────────────────────────────────────────────────────────────┐\n│                    Any MCP Client                           │\n│                                                             │\n│  PGMCP CLI  │  Cursor  │  Claude Desktop  │  VS Code  │ ... │\n│  JSON\u002FCSV   │  Chat    │  AI Assistant    │  Editor   │     │\n└─────────────────────────────────────────────────────────────┘\n         │\n         │ Streamable HTTP \u002F MCP Protocol\n         ▼\n┌─────────────────────────────────────────────────────────────┐\n│                    PGMCP Server                             │\n│                                                             │\n│  🔒 Security    🧠 AI Engine      🌊 Streaming               │\n│  • Input Valid  • Schema Cache    • Auto-Pagination         │\n│  • Audit Log    • OpenAI API      • Memory Management       │\n│  • SQL Guard    • Error Recovery  • Connection Pool         │\n└─────────────────────────────────────────────────────────────┘\n         │\n         │ Read-Only SQL Queries\n         ▼\n┌─────────────────────────────────────────────────────────────┐\n│                Your PostgreSQL Database                     │\n│                                                             │\n│  Any Schema: E-commerce, Analytics, CRM, etc.               │\n│  Tables • Views • Indexes • Functions                       │\n└─────────────────────────────────────────────────────────────┘\n\nExternal AI Services:\nOpenAI API • Anthropic • Local LLMs (Ollama, etc.)\n\nKey Benefits:\n✅ Works with ANY PostgreSQL database (no assumptions about schema)\n✅ No schema modifications required  \n✅ Read-only access (100% safe)\n✅ Automatic streaming for large results\n✅ Intelligent query understanding (singular vs plural)\n✅ Robust error handling (graceful AI failure recovery)\n✅ PostgreSQL case sensitivity support (mixed-case tables)\n✅ Production-ready security and performance\n✅ Universal database compatibility\n✅ Multiple output formats (table, JSON, CSV)\n✅ Free-text search across all columns\n✅ Authentication support\n✅ Comprehensive testing suite\n```\n\n## Features\n\n- **Natural Language to SQL**: Ask questions in plain English\n- **Automatic Streaming**: Handles large result sets automatically  \n- **Safe Read-Only Access**: Prevents any write operations\n- **Text Search**: Search across all text columns\n- **Multiple Output Formats**: Table, JSON, and CSV\n- **PostgreSQL Case Sensitivity**: Handles mixed-case table names correctly\n- **Universal Compatibility**: Works with any PostgreSQL database\n\n### Environment Variables\n\n**Required:**\n- `DATABASE_URL`: PostgreSQL connection string to your existing database\n\n**Optional:**\n- `OPENAI_API_KEY`: OpenAI API key for AI-powered SQL generation\n- `OPENAI_MODEL`: Model to use (default: \"gpt-4o-mini\")\n- `HTTP_ADDR`: Server address (default: \":8080\")\n- `HTTP_PATH`: MCP endpoint path (default: \"\u002Fmcp\")\n- `AUTH_BEARER`: Bearer token for authentication\n\n## Installation\n\n### Download Pre-compiled Binaries\n\n1. Go to [GitHub Releases](https:\u002F\u002Fgithub.com\u002Fsubnetmarco\u002Fpgmcp\u002Freleases)\n2. Download the binary for your platform (Linux, macOS, Windows)\n3. Extract and run:\n\n```bash\n# Example for macOS\u002FLinux\ntar xzf pgmcp_*.tar.gz\ncd pgmcp_*\n.\u002Fpgmcp-server\n```\n\n### Alternative Options\n\n```bash\n# Homebrew (macOS\u002FLinux) - Available after first release\nbrew tap subnetmarco\u002Fhomebrew-tap\nbrew install pgmcp\n\n# Build from source\ngo build -o pgmcp-server .\u002Fserver\ngo build -o pgmcp-client .\u002Fclient\n```\n\n### Docker\u002FKubernetes\n\n```bash\n# Docker\ndocker run -e DATABASE_URL=\"postgres:\u002F\u002Fuser:pass@host:5432\u002Fdb\" \\\n  -p 8080:8080 ghcr.io\u002Fsubnetmarco\u002Fpgmcp:latest\n\n# Kubernetes (see examples\u002F directory for full manifests)\nkubectl create secret generic pgmcp-secret \\\n  --from-literal=database-url=\"postgres:\u002F\u002Fuser:pass@host:5432\u002Fdb\"\nkubectl apply -f examples\u002Fk8s\u002F\n```\n\n#### Quick Start\n\n```bash\n# Set up database (optional - works with any existing PostgreSQL database)\nexport DATABASE_URL=\"postgres:\u002F\u002Fuser:password@localhost:5432\u002Fmydb\"\npsql $DATABASE_URL \u003C schema.sql\n\n# Run server\nexport OPENAI_API_KEY=\"your-api-key\"\n.\u002Fpgmcp-server\n\n# Test with client\n.\u002Fpgmcp-client -ask \"Who is the user that places the most orders?\" -format table\n.\u002Fpgmcp-client -ask \"Show me the top 40 most reviewed items in the marketplace\" -format table\n```\n\n### Environment Variables\n\n**Required:**\n- `DATABASE_URL`: PostgreSQL connection string\n\n**Optional:**\n- `OPENAI_API_KEY`: OpenAI API key for SQL generation\n- `OPENAI_MODEL`: Model to use (default: \"gpt-4o-mini\")\n- `HTTP_ADDR`: Server address (default: \":8080\")\n- `HTTP_PATH`: MCP endpoint path (default: \"\u002Fmcp\")\n- `AUTH_BEARER`: Bearer token for authentication\n\n## Usage Examples\n\n```bash\n# Ask questions in natural language\n.\u002Fpgmcp-client -ask \"What are the top 5 customers?\" -format table\n.\u002Fpgmcp-client -ask \"How many orders were placed today?\" -format json\n\n# Search across all text fields\n.\u002Fpgmcp-client -search \"john\" -format table\n\n# Multiple questions at once\n.\u002Fpgmcp-client -ask \"Show tables\" -ask \"Count users\" -format table\n\n# Different output formats\n.\u002Fpgmcp-client -ask \"Export all data\" -format csv -max-rows 1000\n```\n\n## Example Database\n\nThe project includes two schemas:\n- **`schema.sql`**: Full Amazon-like marketplace with 5,000+ records\n- **`schema_minimal.sql`**: Minimal test schema with mixed-case `\"Categories\"` table\n\n**Key features:**\n- **Mixed-case table names** (`\"Categories\"`) for testing case sensitivity\n- **Composite primary keys** (`order_items`) for testing AI assumptions\n- **Realistic relationships** and data types\n\nUse your own database:\n```bash\nexport DATABASE_URL=\"postgres:\u002F\u002Fuser:pass@host:5432\u002Fyour_db\"\n.\u002Fpgmcp-server\n.\u002Fpgmcp-client -ask \"What tables do I have?\"\n```\n\n## AI Error Handling\n\nWhen AI generates incorrect SQL, PGMCP handles it gracefully:\n\n```json\n{\n  \"error\": \"Column not found in generated query\",\n  \"suggestion\": \"Try rephrasing your question or ask about specific tables\",\n  \"original_sql\": \"SELECT non_existent_column FROM table...\"\n}\n```\n\nInstead of crashing, the system provides helpful feedback and continues operating.\n\n## MCP Integration\n\n### Cursor Integration\n\n```bash\n# Start server\nexport DATABASE_URL=\"postgres:\u002F\u002Fuser:pass@localhost:5432\u002Fyour_db\"\n.\u002Fpgmcp-server\n```\n\nAdd to Cursor settings:\n```json\n{\n  \"mcp.servers\": {\n    \"pgmcp\": {\n      \"transport\": {\n        \"type\": \"http\",\n        \"url\": \"http:\u002F\u002Flocalhost:8080\u002Fmcp\"\n      }\n    }\n  }\n}\n```\n\n### Claude Desktop Integration\n\nEdit `~\u002F.config\u002Fclaude-desktop\u002Fclaude_desktop_config.json`:\n```json\n{\n  \"mcpServers\": {\n    \"pgmcp\": {\n      \"transport\": {\n        \"type\": \"http\",\n        \"url\": \"http:\u002F\u002Flocalhost:8080\u002Fmcp\"\n      }\n    }\n  }\n}\n```\n\n## API Tools\n\n- **`ask`**: Natural language questions → SQL queries with automatic streaming\n- **`search`**: Free-text search across all database text columns  \n- **`stream`**: Advanced streaming for very large result sets with pagination\n\n## Safety Features\n\n- **Read-Only Enforcement**: Blocks write operations (INSERT, UPDATE, DELETE, etc.)\n- **Query Timeouts**: Prevents long-running queries\n- **Input Validation**: Sanitizes and validates all user input\n- **Transaction Isolation**: All queries run in read-only transactions\n\n## Testing\n\n```bash\n# Unit tests\ngo test .\u002Fserver -v\n\n# Integration tests (requires PostgreSQL)\ngo test .\u002Fserver -tags=integration -v\n```\n\n## License\n\nApache 2.0 - See LICENSE file for details.\n\n## Related Projects\n\n- [Model Context Protocol](https:\u002F\u002Fmodelcontextprotocol.io\u002F) - The underlying protocol specification\n- [MCP Go SDK](https:\u002F\u002Fgithub.com\u002Fmodelcontextprotocol\u002Fgo-sdk) - Go implementation of MCP\n\n---\n\nPGMCP makes your PostgreSQL database accessible to AI assistants through natural language while maintaining security through read-only access controls.\n","[![ci](https:\u002F\u002Fgithub.com\u002Fsubnetmarco\u002Fpgmcp\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fsubnetmarco\u002Fpgmcp\u002Factions\u002Fworkflows\u002Fci.yml)\n[![Go Report Card](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fsubnetmarco_pgmcp_readme_2b4a70945b89.png)](https:\u002F\u002Fgoreportcard.com\u002Freport\u002Fgithub.com\u002Fsubnetmarco\u002Fpgmcp)\n[![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-Apache%202.0-blue.svg)](https:\u002F\u002Fopensource.org\u002Flicenses\u002FApache-2.0)\n\n# PGMCP - PostgreSQL 模型上下文协议服务器\n\nPGMCP 通过自然语言查询将 AI 助手连接到 **任何 PostgreSQL 数据库**。用简单的英语提问，即可获得结构化的 SQL 查询结果，并支持自动流式传输和强大的错误处理机制。\n\n**兼容平台**：Cursor、Claude Desktop、VS Code 扩展以及任何 [MCP 兼容客户端](https:\u002F\u002Fmodelcontextprotocol.io\u002F)\n\n## 快速入门\n\nPGMCP 可以连接到 **您现有的 PostgreSQL 数据库**，并通过自然语言查询使其对 AI 助手开放。\n\n### 前提条件\n- PostgreSQL 数据库（包含您模式的现有数据库）\n- OpenAI API 密钥（可选，用于 AI 驱动的 SQL 生成）\n\n### 基本使用方法\n\n```bash\n# 设置环境变量\nexport DATABASE_URL=\"postgres:\u002F\u002Fuser:password@localhost:5432\u002Fyour-existing-db\"\nexport OPENAI_API_KEY=\"your-api-key\"  # 可选\n\n# 运行服务器（使用预编译的二进制文件）\n.\u002Fpgmcp-server\n\n# 在另一个终端中使用客户端进行测试\n.\u002Fpgmcp-client -ask \"What tables do I have?\" -format table\n.\u002Fpgmcp-client -ask \"Who is the customer that has placed the most orders?\" -format table\n.\u002Fpgmcp-client -search \"john\" -format table\n```\n\n其工作流程如下：\n\n```\n👤 用户 \u002F AI 助手\n         │\n         │ “谁是顶级客户？”\n         ▼\n┌─────────────────────────────────────────────────────────────┐\n│                    任意 MCP 客户端                           │\n│                                                             │\n│  PGMCP CLI  │  Cursor  │  Claude Desktop  │  VS Code  │ ... │\n│  JSON\u002FCSV   │  聊天    │  AI 助手        │  编辑器   │     │\n└─────────────────────────────────────────────────────────────┘\n         │\n         │ 流式 HTTP \u002F MCP 协议\n         ▼\n┌─────────────────────────────────────────────────────────────┐\n│                    PGMCP 服务器                             │\n│                                                             │\n│  🔒 安全    🧠 AI 引擎      🌊 流式传输               │\n│  • 输入验证  • 模式缓存    • 自动分页         │\n│  • 审计日志  • OpenAI API  • 内存管理       │\n│  • SQL 防护  • 错误恢复    • 连接池         │\n└─────────────────────────────────────────────────────────────┘\n         │\n         │ 只读 SQL 查询\n         ▼\n┌─────────────────────────────────────────────────────────────┐\n│                您的 PostgreSQL 数据库                     │\n│                                                             │\n│  任意模式：电商、分析、CRM 等                               │\n│  表 • 视图 • 索引 • 函数                                   │\n└─────────────────────────────────────────────────────────────┘\n\n外部 AI 服务：\nOpenAI API • Anthropic • 本地 LLM（Ollama 等）\n\n主要优势：\n✅ 适用于任何 PostgreSQL 数据库（无需假设模式）\n✅ 无需修改模式  \n✅ 只读访问（100% 安全）\n✅ 自动流式传输大型结果\n✅ 智能查询理解（单数与复数区分）\n✅ 强大的错误处理机制（优雅的 AI 故障恢复）\n✅ 支持 PostgreSQL 的大小写敏感性（混合大小写表名）\n✅ 生产级安全性和性能\n✅ 通用数据库兼容性\n✅ 多种输出格式（表格、JSON、CSV）\n✅ 全文搜索功能，可跨所有列\n✅ 支持身份验证\n✅ 全面的测试套件\n```\n\n## 功能特性\n\n- **自然语言转 SQL**：用简单英语提问\n- **自动流式传输**：自动处理大型结果集\n- **安全只读访问**：防止任何写操作\n- **全文搜索**：可在所有文本列中搜索\n- **多种输出格式**：表格、JSON 和 CSV\n- **PostgreSQL 大小写敏感性**：正确处理混合大小写表名\n- **通用兼容性**：适用于任何 PostgreSQL 数据库\n\n### 环境变量\n\n**必填：**\n- `DATABASE_URL`：指向您现有数据库的 PostgreSQL 连接字符串\n\n**可选：**\n- `OPENAI_API_KEY`：用于 AI 驱动的 SQL 生成的 OpenAI API 密钥\n- `OPENAI_MODEL`：使用的模型（默认为“gpt-4o-mini”）\n- `HTTP_ADDR`：服务器地址（默认为“:8080”）\n- `HTTP_PATH`：MCP 端点路径（默认为“\u002Fmcp”）\n- `AUTH_BEARER`：用于身份验证的 Bearer 令牌\n\n## 安装\n\n### 下载预编译二进制文件\n\n1. 访问 [GitHub 发布页面](https:\u002F\u002Fgithub.com\u002Fsubnetmarco\u002Fpgmcp\u002Freleases)\n2. 下载适合您平台的二进制文件（Linux、macOS、Windows）\n3. 解压并运行：\n\n```bash\n# macOS\u002FLinux 示例\ntar xzf pgmcp_*.tar.gz\ncd pgmcp_*\n.\u002Fpgmcp-server\n```\n\n### 其他安装方式\n\n```bash\n# Homebrew（macOS\u002FLinux） - 第一次发布后可用\nbrew tap subnetmarco\u002Fhomebrew-tap\nbrew install pgmcp\n\n# 从源码构建\ngo build -o pgmcp-server .\u002Fserver\ngo build -o pgmcp-client .\u002Fclient\n```\n\n### Docker\u002FKubernetes\n\n```bash\n# Docker\ndocker run -e DATABASE_URL=\"postgres:\u002F\u002Fuser:pass@host:5432\u002Fdb\" \\\n  -p 8080:8080 ghcr.io\u002Fsubnetmarco\u002Fpgmcp:latest\n\n# Kubernetes（完整清单请参见 examples\u002F 目录）\nkubectl create secret generic pgmcp-secret \\\n  --from-literal=database-url=\"postgres:\u002F\u002Fuser:pass@host:5432\u002Fdb\"\nkubectl apply -f examples\u002Fk8s\u002F\n```\n\n#### 快速开始\n\n```bash\n# 设置数据库（可选 - 适用于任何现有 PostgreSQL 数据库）\nexport DATABASE_URL=\"postgres:\u002F\u002Fuser:password@localhost:5432\u002Fmydb\"\npsql $DATABASE_URL \u003C schema.sql\n\n# 运行服务器\nexport OPENAI_API_KEY=\"your-api-key\"\n.\u002Fpgmcp-server\n\n# 使用客户端测试\n.\u002Fpgmcp-client -ask \"Who is the user that places the most orders?\" -format table\n.\u002Fpgmcp-client -ask \"Show me the top 40 most reviewed items in the marketplace\" -format table\n```\n\n### 环境变量\n\n**必填：**\n- `DATABASE_URL`：PostgreSQL 连接字符串\n\n**可选：**\n- `OPENAI_API_KEY`：用于 SQL 生成的 OpenAI API 密钥\n- `OPENAI_MODEL`：使用的模型（默认为“gpt-4o-mini”）\n- `HTTP_ADDR`：服务器地址（默认为“:8080”）\n- `HTTP_PATH`：MCP 端点路径（默认为“\u002Fmcp”）\n- `AUTH_BEARER`：用于身份验证的 Bearer 令牌\n\n## 使用示例\n\n```bash\n# 用自然语言提问\n.\u002Fpgmcp-client -ask \"What are the top 5 customers?\" -format table\n.\u002Fpgmcp-client -ask \"How many orders were placed today?\" -format json\n\n# 在所有文本字段中搜索\n.\u002Fpgmcp-client -search \"john\" -format table\n\n# 一次性执行多个查询\n.\u002Fpgmcp-client -ask \"Show tables\" -ask \"Count users\" -format table\n\n# 不同的输出格式\n.\u002Fpgmcp-client -ask \"Export all data\" -format csv -max-rows 1000\n```\n\n## 示例数据库\n\n该项目包含两个模式：\n- **`schema.sql`**：完整的类亚马逊式电商平台，包含 5,000 多条记录\n- **`schema_minimal.sql`**：最小化的测试模式，其中 `Categories` 表名采用大小写混合形式\n\n**主要特性：**\n- **大小写混合的表名**（如 `\"Categories\"`），用于测试大小写敏感性\n- **复合主键**（如 `order_items`），用于检验 AI 的假设\n- **真实的表间关系**和数据类型\n\n使用您自己的数据库：\n```bash\nexport DATABASE_URL=\"postgres:\u002F\u002Fuser:pass@host:5432\u002Fyour_db\"\n.\u002Fpgmcp-server\n.\u002Fpgmcp-client -ask \"What tables do I have?\"\n```\n\n## AI 错误处理\n\n当 AI 生成错误的 SQL 语句时，PGMCP 会以优雅的方式进行处理：\n\n```json\n{\n  \"error\": \"生成的查询中未找到列\",\n  \"suggestion\": \"请尝试重新表述问题，或询问特定的表\",\n  \"original_sql\": \"SELECT non_existent_column FROM table...\"\n}\n```\n\n系统不会崩溃，而是提供有用的反馈并继续运行。\n\n## MCP 集成\n\n### Cursor 集成\n\n```bash\n# 启动服务器\nexport DATABASE_URL=\"postgres:\u002F\u002Fuser:pass@localhost:5432\u002Fyour_db\"\n.\u002Fpgmcp-server\n```\n\n在 Cursor 设置中添加：\n```json\n{\n  \"mcp.servers\": {\n    \"pgmcp\": {\n      \"transport\": {\n        \"type\": \"http\",\n        \"url\": \"http:\u002F\u002Flocalhost:8080\u002Fmcp\"\n      }\n    }\n  }\n}\n```\n\n### Claude Desktop 集成\n\n编辑 `~\u002F.config\u002Fclaude-desktop\u002Fclaude_desktop_config.json`：\n```json\n{\n  \"mcpServers\": {\n    \"pgmcp\": {\n      \"transport\": {\n        \"type\": \"http\",\n        \"url\": \"http:\u002F\u002Flocalhost:8080\u002Fmcp\"\n      }\n    }\n  }\n}\n```\n\n## API 工具\n\n- **`ask`**：自然语言问题 → 自动流式传输的 SQL 查询\n- **`search`**：跨所有数据库文本列的自由文本搜索\n- **`stream`**：针对超大数据集的高级流式传输，并支持分页\n\n## 安全特性\n\n- **只读强制执行**：阻止写操作（INSERT、UPDATE、DELETE 等）\n- **查询超时**：防止长时间运行的查询\n- **输入验证**：对所有用户输入进行清理和验证\n- **事务隔离**：所有查询均在只读事务中执行\n\n## 测试\n\n```bash\n# 单元测试\ngo test .\u002Fserver -v\n\n# 集成测试（需要 PostgreSQL）\ngo test .\u002Fserver -tags=integration -v\n```\n\n## 许可证\n\nApache 2.0 - 详情请参阅 LICENSE 文件。\n\n## 相关项目\n\n- [模型上下文协议](https:\u002F\u002Fmodelcontextprotocol.io\u002F) - 底层协议规范\n- [MCP Go SDK](https:\u002F\u002Fgithub.com\u002Fmodelcontextprotocol\u002Fgo-sdk) - MCP 的 Go 实现\n\n---\n\nPGMCP 通过自然语言使您的 PostgreSQL 数据库能够被 AI 助手访问，同时通过只读访问控制确保安全性。","# PGMCP 快速上手指南\n\nPGMCP 是一个基于 Model Context Protocol (MCP) 的 PostgreSQL 服务器，允许 AI 助手（如 Cursor、Claude Desktop）通过自然语言直接查询你的 PostgreSQL 数据库。它支持自动流式传输、只读安全访问以及多种输出格式。\n\n## 环境准备\n\n在开始之前，请确保满足以下要求：\n\n*   **操作系统**：Linux, macOS 或 Windows。\n*   **数据库**：一个现有的 PostgreSQL 数据库（无需修改表结构）。\n*   **API 密钥（可选）**：OpenAI API Key，用于启用 AI 驱动的 SQL 生成功能。如果不配置，部分智能查询功能可能受限。\n*   **网络**：确保本地可以访问数据库端口（默认 5432）及 OpenAI 服务（如需使用 AI 功能）。\n\n## 安装步骤\n\n你可以通过下载预编译二进制文件或使用 Docker 快速部署。\n\n### 方法一：下载预编译二进制文件（推荐）\n\n1.  访问 [GitHub Releases](https:\u002F\u002Fgithub.com\u002Fsubnetmarco\u002Fpgmcp\u002Freleases) 页面。\n2.  下载对应你操作系统的压缩包（`pgmcp_*.tar.gz` 或 `.zip`）。\n3.  解压并运行：\n\n```bash\n# 以 macOS\u002FLinux 为例\ntar xzf pgmcp_*.tar.gz\ncd pgmcp_*\n# 赋予执行权限（如需）\nchmod +x pgmcp-server pgmcp-client\n```\n\n### 方法二：从源码构建\n\n如果你已安装 Go 环境：\n\n```bash\ngo build -o pgmcp-server .\u002Fserver\ngo build -o pgmcp-client .\u002Fclient\n```\n\n### 方法三：使用 Docker\n\n```bash\ndocker run -e DATABASE_URL=\"postgres:\u002F\u002Fuser:pass@host:5432\u002Fdb\" \\\n  -p 8080:8080 ghcr.io\u002Fsubnetmarco\u002Fpgmcp:latest\n```\n\n## 基本使用\n\n### 1. 配置环境变量\n\n设置数据库连接字符串。如果需要 AI 生成 SQL，还需设置 OpenAI Key。\n\n```bash\n# 替换为你的实际数据库连接信息\nexport DATABASE_URL=\"postgres:\u002F\u002Fuser:password@localhost:5432\u002Fyour-existing-db\"\n\n# 可选：设置 OpenAI API Key 以启用智能查询\nexport OPENAI_API_KEY=\"your-api-key\"\n```\n\n### 2. 启动服务器\n\n在终端中运行服务器：\n\n```bash\n.\u002Fpgmcp-server\n```\n*默认监听地址为 `http:\u002F\u002Flocalhost:8080\u002Fmcp`。*\n\n### 3. 测试查询\n\n打开一个新的终端窗口，使用自带的客户端工具进行测试：\n\n**查询表结构：**\n```bash\n.\u002Fpgmcp-client -ask \"What tables do I have?\" -format table\n```\n\n**自然语言提问（需配置 OPENAI_API_KEY）：**\n```bash\n.\u002Fpgmcp-client -ask \"Who is the customer that has placed the most orders?\" -format table\n```\n\n**全文搜索：**\n```bash\n.\u002Fpgmcp-client -search \"john\" -format table\n```\n\n**指定输出格式（JSON\u002FCSV）：**\n```bash\n.\u002Fpgmcp-client -ask \"How many orders were placed today?\" -format json\n```\n\n### 4. 集成到 AI 编辑器（可选）\n\n若要在 **Cursor** 或 **Claude Desktop** 中使用，请在其配置文件中添加 MCP 服务器信息：\n\n**Cursor 配置 (`settings.json`)：**\n```json\n{\n  \"mcp.servers\": {\n    \"pgmcp\": {\n      \"transport\": {\n        \"type\": \"http\",\n        \"url\": \"http:\u002F\u002Flocalhost:8080\u002Fmcp\"\n      }\n    }\n  }\n}\n```\n\n**Claude Desktop 配置 (`claude_desktop_config.json`)：**\n```json\n{\n  \"mcpServers\": {\n    \"pgmcp\": {\n      \"transport\": {\n        \"type\": \"http\",\n        \"url\": \"http:\u002F\u002Flocalhost:8080\u002Fmcp\"\n      }\n    }\n  }\n}\n```\n\n配置完成后，即可在聊天窗口中直接用自然语言询问数据库内容。PGMCP 默认仅执行只读查询，确保数据安全。","某电商公司的数据分析师需要在晨会前快速从庞大的 PostgreSQL 订单库中提取特定用户行为数据，以支持临时决策。\n\n### 没有 pgmcp 时\n- 分析师必须手动编写复杂的 SQL 语句，反复查阅文档确认表结构和字段名，耗时且容易出错。\n- 遇到不熟悉的业务逻辑（如“复购率最高的地区”），需先向开发人员请教 schema 关系，沟通成本高。\n- 查询结果若数据量过大，容易导致客户端卡顿或超时，需要人工添加分页逻辑重新执行。\n- 无法直接在 Cursor 或 Claude Desktop 等 AI 编程助手环境中获取实时数据，必须切换工具打断工作流。\n\n### 使用 pgmcp 后\n- 分析师直接在 AI 助手对话框输入自然语言“找出上个月复购率最高的三个地区”，pgmcp 自动解析并生成精准 SQL。\n- pgmcp 内置智能 Schema 缓存，能理解“客户”与\"users\"表的关联，无需人工干预即可处理复杂连接查询。\n- 面对海量数据，pgmcp 自动启用流式传输和分页机制，瞬间返回结构化表格，彻底告别超时等待。\n- 在 Cursor 或 VS Code 中即可无缝调用数据库，数据结果直接嵌入代码上下文，实现“提问即分析”的流畅体验。\n\npgmcp 将原本繁琐的“查文档 - 写 SQL - 调错”流程简化为自然的对话交互，让非技术人员也能安全、高效地直接挖掘数据库价值。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fsubnetmarco_pgmcp_4bfd1f06.png","subnetmarco","Marco Palladino","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fsubnetmarco_543889bd.jpg","CTO at @Kong. \r\n\r\nWe are hiring engineers: https:\u002F\u002Fkonghq.com\u002Fcareers","Kong","San Francisco","marco@konghq.com","https:\u002F\u002Fkonghq.com","https:\u002F\u002Fgithub.com\u002Fsubnetmarco",[24,28,32],{"name":25,"color":26,"percentage":27},"Go","#00ADD8",96.7,{"name":29,"color":30,"percentage":31},"Shell","#89e051",3.1,{"name":33,"color":34,"percentage":35},"Dockerfile","#384d54",0.2,527,61,"2026-04-04T15:29:47","NOASSERTION",2,"Linux, macOS, Windows","不需要 GPU","未说明",{"notes":45,"python":46,"dependencies":47},"该工具是基于 Go 语言编写的二进制程序，无需 Python 环境或 GPU。核心依赖是现有的 PostgreSQL 数据库。若需使用自然语言转 SQL 功能，需配置 OpenAI API Key（默认模型 gpt-4o-mini），也可选择不开启此功能。支持通过 Docker 或直接下载预编译二进制文件运行。","不适用 (基于 Go 语言)",[48,49,50],"PostgreSQL 数据库","Go (用于从源码构建)","OpenAI API Key (可选，用于 AI 生成 SQL)",[52,53,54,55],"Agent","数据工具","图像","开发框架",[57,58,59,60,61,62,63,64,65,66,67,68],"agent","agentic-ai","ai","analytics","artificial-intelligence","kong","mcp","mcp-server","postgres","postgresql","data-analysis","database",null,"ready","2026-03-27T02:49:30.150509","2026-04-06T23:03:40.939592",[74,79,84,89,94,98],{"id":75,"question_zh":76,"answer_zh":77,"source_url":78},20274,"如何获取编译好的二进制文件而不需要本地编译源码？","项目已提供完整的发布自动化流程，包含官方二进制文件。您可以直接在 Releases 页面下载（例如 v0.3.0 及以上版本）。此外，项目还支持通过 Homebrew 安装，并提供了 Docker 和 Kubernetes 的使用示例。","https:\u002F\u002Fgithub.com\u002Fsubnetmarco\u002Fpgmcp\u002Fissues\u002F9",{"id":80,"question_zh":81,"answer_zh":82,"source_url":83},20275,"如果数据库表名以大写字母开头（例如 \"Book\"），工具无法识别怎么办？","该问题已在后续版本中修复。此前工具可能将表名强制转换为小写导致找不到表（如将 \"Book\" 误认为 \"book\"）。如果您使用 Prisma 等生成混合大小写表名的工具，请升级到最新修复版本即可正常支持。","https:\u002F\u002Fgithub.com\u002Fsubnetmarco\u002Fpgmcp\u002Fissues\u002F3",{"id":85,"question_zh":86,"answer_zh":87,"source_url":88},20276,"如何确保只读模式的安全性，防止 LLM 生成的 SQL 逃逸并修改数据库？","工具底层使用 `pgx` PostgreSQL 驱动强制开启只读事务（`pgx.TxOptions{AccessMode: pgx.ReadOnly}`）。即使生成的 SQL 包含 `ROLLBACK` 或 `DROP TABLE` 等试图逃逸的指令，驱动层也会阻止写入操作。此外，维护者已额外增加了安全测试用例以强化这一机制。","https:\u002F\u002Fgithub.com\u002Fsubnetmarco\u002Fpgmcp\u002Fissues\u002F7",{"id":90,"question_zh":91,"answer_zh":92,"source_url":93},20277,"该项目有哪些典型的实际应用场景？","一个典型场景是在 SaaS 应用（如线索管理系统）中，允许管理员用户执行即席（ad-hoc）数据库查询。这能提供比标准报表更详细的推理分析。用户可以在 UI 中输入提示词获取 SQL 和结果，并根据结果微调提示词重新运行，从而灵活获取数据（例如统计包含开放和关闭状态的总线索数）。","https:\u002F\u002Fgithub.com\u002Fsubnetmarco\u002Fpgmcp\u002Fissues\u002F6",{"id":95,"question_zh":96,"answer_zh":97,"source_url":93},20278,"在生产环境中使用时，如何处理敏感数据的访问控制？","虽然工具本身支持自然语言查询，但在实际部署时（如线索管理应用），通常需要添加自定义逻辑来限制对特定表或数据的查询。开发者需要在应用层面对查询范围进行约束，以防止用户访问未授权的数据，同时提醒用户注意查询结果的上下文含义（如总数是否包含已关闭的记录）。",{"id":99,"question_zh":100,"answer_zh":101,"source_url":78},20279,"除了直接下载二进制文件，还有哪些推荐的部署方式？","除了下载官方二进制文件外，项目推荐使用 Docker 容器化部署，同时也提供了 Kubernetes (K8s) 的配置示例。对于 macOS 用户，还可以通过官方支持的 Homebrew 包管理器进行安装。",[103],{"id":104,"version":105,"summary_zh":106,"released_at":107},118309,"v0.3.0","## PGMCP v0.3.0\n\nPostgreSQL 模型上下文协议服务器 - 针对多个平台的预编译二进制文件。\n\n### 快速入门\n\n1. 请在下方下载适用于您平台的相应二进制文件。\n2. 解压压缩包。\n3. 设置环境变量：\n   ```bash\n   export DATABASE_URL=\"postgres:\u002F\u002Fuser:password@localhost:5432\u002Fmydb\"\n   export OPENAI_API_KEY=\"your-api-key\"  # 可选\n   ```\n4. 运行服务器：`.\u002Fpgmcp-server`\n5. 使用客户端进行测试：`.\u002Fpgmcp-client -ask \"What tables do I have?\" -format table`\n\n### 平台支持\n\n- **Linux**: x86_64 和 ARM64\n- **macOS**: Intel 和 Apple Silicon (M1\u002FM2\u002FM3)\n- **Windows**: x86_64 和 ARM64\n\n## 更改日志\n\n### 通过包管理器安装\n\n```bash\n# Homebrew (macOS\u002FLinux)\nbrew tap subnetmarco\u002Fhomebrew-tap\nbrew install pgmcp\n\n# Linux 软件包\nsudo apt install .\u002Fpgmcp_0.3.0_linux_amd64.deb  # Debian\u002FUbuntu\nsudo rpm -i pgmcp_0.3.0_linux_amd64.rpm         # RedHat\u002FCentOS\n```\n\n### Docker\n\n```bash\n# 服务器\ndocker run -e DATABASE_URL=your_db_url -e OPENAI_API_KEY=your_key ghcr.io\u002Fsubnetmarco\u002Fpgmcp:v0.3.0\n```\n\n**完整更改日志**：https:\u002F\u002Fgithub.com\u002Fsubnetmarco\u002Fpgmcp\u002Fcompare\u002F0.2...v0.3.0","2025-09-25T18:20:28",[109,118,126,135,143,151],{"id":110,"name":111,"github_repo":112,"description_zh":113,"stars":114,"difficulty_score":115,"last_commit_at":116,"category_tags":117,"status":70},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[52,55,54,53],{"id":119,"name":120,"github_repo":121,"description_zh":122,"stars":123,"difficulty_score":115,"last_commit_at":124,"category_tags":125,"status":70},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[55,54,52],{"id":127,"name":128,"github_repo":129,"description_zh":130,"stars":131,"difficulty_score":40,"last_commit_at":132,"category_tags":133,"status":70},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",141543,"2026-04-06T11:32:54",[55,52,134],"语言模型",{"id":136,"name":137,"github_repo":138,"description_zh":139,"stars":140,"difficulty_score":40,"last_commit_at":141,"category_tags":142,"status":70},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107888,"2026-04-06T11:32:50",[55,54,52],{"id":144,"name":145,"github_repo":146,"description_zh":147,"stars":148,"difficulty_score":115,"last_commit_at":149,"category_tags":150,"status":70},4487,"LLMs-from-scratch","rasbt\u002FLLMs-from-scratch","LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。\n\n该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。\n\nLLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备",90106,"2026-04-06T11:19:32",[134,54,52,55],{"id":152,"name":153,"github_repo":154,"description_zh":155,"stars":156,"difficulty_score":115,"last_commit_at":157,"category_tags":158,"status":70},4292,"Deep-Live-Cam","hacksider\u002FDeep-Live-Cam","Deep-Live-Cam 是一款专注于实时换脸与视频生成的开源工具，用户仅需一张静态照片，即可通过“一键操作”实现摄像头画面的即时变脸或制作深度伪造视频。它有效解决了传统换脸技术流程繁琐、对硬件配置要求极高以及难以实时预览的痛点，让高质量的数字内容创作变得触手可及。\n\n这款工具不仅适合开发者和技术研究人员探索算法边界，更因其极简的操作逻辑（仅需三步：选脸、选摄像头、启动），广泛适用于普通用户、内容创作者、设计师及直播主播。无论是为了动画角色定制、服装展示模特替换，还是制作趣味短视频和直播互动，Deep-Live-Cam 都能提供流畅的支持。\n\n其核心技术亮点在于强大的实时处理能力，支持口型遮罩（Mouth Mask）以保留使用者原始的嘴部动作，确保表情自然精准；同时具备“人脸映射”功能，可同时对画面中的多个主体应用不同面孔。此外，项目内置了严格的内容安全过滤机制，自动拦截涉及裸露、暴力等不当素材，并倡导用户在获得授权及明确标注的前提下合规使用，体现了技术发展与伦理责任的平衡。",88924,"2026-04-06T03:28:53",[55,54,52,159],"视频"]