PostgreSQL MCP服务器

PostgreSQL MCP服务器

A. 基于FastMCP 只读PostgreSQL MCP（模型上下文协议）服务器，设计用于在 AWS基岩代理核心运行时.

📋 更新日志

[1.1.0] - 2026-02-19

添加

• 数学实用工具: math_add, math_subtract, math_multiply, math_divide --用于在没有数据库的情况下测试AgentCore运行时连接
• AWS Secrets Manager集成：自动获取 DATABASE_URL 和 MCP_API_KEY 来自秘密 postgres-mcp/credentials 在AWS中运行时(AWS_REGION 已设置）
• IAM身份验证旁路: APIKeyMiddleware 跳跃 X-API-Key 在AgentCore内部运行时进行验证（IAM/SigV4在平台级别处理身份验证）
• mcp-proxy-for-aws IDE集成：通过SigV4签名的本地代理将Windsurf/Cursor直接连接到部署的AgentCore运行时（否 X-API-Key 需要IDE）
• boto3 依赖：添加到 requirements.txt 用于访问AWS Secrets Manager
• 部署指南：全面 docs/DEPLOYMENT_GUIDE.md 使用Mermaid架构图涵盖CLI、CloudFormation和手动Docker部署选项
• 直接代码部署支持: agentcore deploy 直接打包和部署代码——部署AgentCore不需要Docker构建

改变

• 服务器现在使用 mcp.streamable_http_app() 包裹着 APIKeyMiddleware ASGI中间件（以前依赖于FastMCP的内置运行器）
• get_secrets_from_aws() 在启动时被调用；环境变量可作为本地开发的后备方案
• 资源URI模式简化为 postgres://schema/{table_name} （FastMCP模板格式）

特性

• 只读访问：所有查询都在 READ ONLY 交易
• 可流式HTTP传输：与AWS AgentCore运行时兼容
• 无状态操作：支持会话隔离的水平扩展
• 数据库架构发现：列出表并描述列结构
• 健康检查端点：容器已准备就绪 /health 端点
• API密钥验证：安全访问 X-API-Key 标头或承载令牌（在AWS中自动禁用）
• AWS机密管理器：部署到AgentCore时自动获取凭据
• 数学实用工具：用于连接测试的内置算术工具

工具

资源

资源是基于数据库表动态生成的。

当你打电话的时候 list_resources()，服务器返回 public 具有以下URI的模式：

• postgres://schema/users
• postgres://schema/orders

先决条件

• Python 3.10+
• PostgreSQL数据库
• Docker（用于容器化部署）

安装

# Clone or navigate to the project
cd postgres-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

配置

设置所需的环境变量：

export DATABASE_URL="postgresql://user:password@host:port/database"
export MCP_API_KEY="your-secure-api-key"  # Optional but recommended

或者创建一个 .env 文件基于 .env.example:

cp .env.example .env
# Edit .env with your database credentials and API key

环境变量

AWS机密管理器：何时 AWS_REGION 设置和 DATABASE_URL 如果不存在，服务器会自动从名为的密钥中获取凭据 postgres-mcp/credentials （按键： DATABASE_URL, MCP_API_KEY).

本地开发

启动MCP服务器

python mcp_server.py

服务器将于启动 http://0.0.0.0:8000/mcp

使用MCP客户端进行测试

在单独的终端中：

python mcp_client.py

健康检查

curl http://localhost:8000/health

使用API密钥进行测试

# With X-API-Key header
curl -H "X-API-Key: your-api-key" http://localhost:8000/mcp

# With Authorization Bearer
curl -H "Authorization: Bearer your-api-key" http://localhost:8000/mcp

Docker部署

塑造形象

docker build -t postgres-mcp .

运行容器

docker run -d \
  -p 8000:8000 \
  -e DATABASE_URL="postgresql://user:password@host:port/database" \
  -e MCP_API_KEY="your-secure-api-key" \
  --name postgres-mcp \
  postgres-mcp

AWS基岩代理核心部署

此服务器专为部署在AWS Bedrock AgentCore Runtime上而设计。

项目结构

postgres-mcp/
├── mcp_server.py          # Main MCP server (FastMCP + ASGI middleware)
├── mcp_client.py          # Local testing client
├── requirements.txt       # Python dependencies
├── Dockerfile             # Container configuration
├── .env.example           # Environment template
├── docs/
│   └── DEPLOYMENT_GUIDE.md  # Full AgentCore deployment guide
└── README.md              # This file

看 docs/DEPLOYMENT_GUIDE.md 获取全面的部署说明，包括CLI、CloudFormation和手动Docker选项。

部署到AgentCore（推荐：CLI）

1. 安装AgentCore工具包:

   复制

   pip install bedrock-agentcore-starter-toolkit
   

2. 配置:

   复制

   export AWS_SHARED_CREDENTIALS_FILE=$(pwd)/.aws/credentials
   export AWS_PROFILE=<your-aws-profile>
   
   agentcore configure -e mcp_server.py \
     --protocol MCP \
     --disable-memory \
     --name postgres_mcp \
     --non-interactive \
     --region us-west-2
   

3. 部署 （直接代码部署——不需要Docker）：

   复制

   agentcore deploy
   

4. 验证:

   复制

   agentcore status
   # Agent ARN: arn:aws:bedrock-agentcore:us-west-2:<account>:runtime/postgres_mcp-<id>
   

5. 测试:

   复制

   agentcore invoke '{"jsonrpc":"2.0","method":"tools/list","id":1}'
   agentcore invoke '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"math_add","arguments":{"a":10,"b":5}},"id":2}'
   

重要：在代理名称中使用下划线(postgres_mcp)，而不是连字符。看 docs/DEPLOYMENT_GUIDE.md CloudFormation和手动Docker选项。

AgentCore的关键配置

服务器使用这些设置来实现AgentCore兼容性：

mcp = FastMCP(
    name="postgres-mcp",
    host="0.0.0.0",
    port=8000,
    stateless_http=True,  # Required for AgentCore
)

# Wrap with API key middleware and serve via uvicorn
app = mcp.streamable_http_app()
app = APIKeyMiddleware(app)
uvicorn.run(app, host="0.0.0.0", port=8000)

• stateless_http=True --AgentCore的无状态请求模型所必需的
• APIKeyMiddleware --在以下情况下自动绕过 AWS_REGION 已设置（AgentCore通过IAM处理身份验证）
• streamable_http_app() --在以下位置公开MCP服务器 /mcp 使用流式HTTP传输

安全注意事项

• API密钥验证：所有端点（除 /health)在本地运行时需要有效的API密钥
• IAM/SigV4（代理核心）：当部署到AgentCore时， X-API-Key 中间件自动禁用——AWS IAM在平台级别处理身份验证
• AWS机密管理器：凭据在启动时从以下位置获取 postgres-mcp/credentials；从未硬编码
• 只读：所有查询都在内部执行 BEGIN TRANSACTION READ ONLY 并且总是被回滚
• 连接池：用途 asyncpg 连接池（最少1个，最多10个连接，60秒超时）
• 无DDL/DML：只允许SELECT和read操作

认证

示例用法

postgres_query工具

{
  "name": "postgres_query",
  "arguments": {
    "sql": "SELECT * FROM users LIMIT 10"
  }
}

Windsurf/IDE MCP配置

本地服务器

添加到您的 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "postgresql-local": {
      "serverUrl": "http://localhost:8000/mcp",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

AWS基岩代理核心（已部署）

使用 mcp-proxy-for-aws 使用SigV4身份验证直接连接到AgentCore运行时--否 X-API-Key 必修的：

{
  "mcpServers": {
    "agentcore-postgres-mcp": {
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/<url-encoded-agent-arn>/invocations?qualifier=DEFAULT"
      ],
      "env": {
        "AWS_PROFILE": "<your-aws-profile>",
        "AWS_REGION": "us-west-2",
        "AWS_SHARED_CREDENTIALS_FILE": "/path/to/postgres-mcp/.aws/credentials"
      }
    }
  }
}

URL中的代理ARN必须进行URL编码（替换 : 随着 %3A, / 随着 %2F).需要 uv 已安装(brew install uv).

重新加载MCP服务器后，所有5个工具都将出现在IDE中： postgres_query, math_add, math_subtract, math_multiply, math_divide.

故障排除

连接问题

1. 验证 DATABASE_URL 设置正确
2. 检查数据库是否可以从服务器访问
3. 确保PostgreSQL允许来自服务器IP的连接

健康检查失败

1. 检查数据库连接
2. 查看服务器日志中的错误
3. 验证端口8000是否未被阻塞

许可证

MIT许可证