# AWS Labs Aurora DSQL MCP 服务器
适用于 Aurora DSQL 的 AWS Labs 模型上下文协议（MCP）服务器
## 功能
+ 将人类可读的问题和命令转换为结构化的、与 Postgres 兼容的 SQL 查询，并对已配置的 Aurora DSQL 数据库执行这些查询。
+ 默认情况下为只读模式，可通过 `--allow-writes` 启用事务
+ 在请求间重用连接以提升性能
+ 内置 Aurora DSQL 文档、搜索及最佳实践建议访问功能
## 可用工具
### 数据库操作
+ **readonly\$1query**：向您的 DSQL 集群执行只读 SQL 查询
+ **transact**：在事务中执行写入操作（需使用 `--allow-writes`）
+ **get\$1schema**：检索表架构信息
### 文档与建议
+ **dsql\$1search\$1documentation**：搜索 Aurora DSQL 文档
+ 参数：`search_phrase`（必需）、`limit`（可选）
+ **dsql\$1read\$1documentation**：读取特定的 DSQL 文档页面
+ 参数：`url`（必需）、`start_index`（可选）、`max_length`（可选）
+ **dsql\$1recommend**：获取 DSQL 最佳实践的建议
+ 参数：`url`（必需）
## 先决条件
1. 具有 [Aurora DSQL 集群](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html)的 AWS 账户
1. 此 MCP 服务器只能在您的 LLM 客户端所在的主机上本地运行。
1. 设置具有 AWS 服务的访问权限的 AWS 凭证
+ 您需要一个 AWS 账户，其角色需包含以下权限：
+ `dsql:DbConnectAdmin`：以管理员用户身份连接到 DSQL 集群
+ `dsql:DbConnect`：使用自定义数据库角色连接到 DSQL 集群（仅在使用非管理员用户时需要此权限）
+ 通过 `aws configure` 或环境变量配置 AWS 凭证
## 安装
对于大多数工具，按照[默认安装](#default-installation)说明更新配置就应该足够了。
对 [Claude Code](#claude-code) 和 [Codex](#codex) 分别概述了说明。
### 默认安装：更新相关的 MCP 配置文件
#### 使用 `uv`
1. 从 [Astral](https://docs.astral.sh/uv/getting-started/installation/) 或 [GitHub README](https://github.com/astral-sh/uv#installation) 安装 `uv`
1. 使用 `uv python install 3.10` 安装 Python
在 MCP 客户端配置中配置 MCP 服务器（[查找 MCP 配置文件](#finding-mcp-config-file)）
```
{
"mcpServers": {
"awslabs.aurora-dsql-mcp-server": {
"command": "uvx",
"args": [
"awslabs.aurora-dsql-mcp-server@latest",
"--cluster_endpoint",
"[your dsql cluster endpoint, e.g. abcdefghijklmnopqrst234567.dsql.us-east-1.on.aws]",
"--region",
"[your dsql cluster region, e.g. us-east-1]",
"--database_user",
"[your dsql username, e.g. admin]",
"--profile",
"[your aws profile, e.g. default]"
],
"env": {
"FASTMCP_LOG_LEVEL": "ERROR"
},
"disabled": false,
"autoApprove": []
}
}
}
```
#### Windows 安装
对于 Windows 用户，MCP 服务器配置格式略有不同：
```
{
"mcpServers": {
"awslabs.aurora-dsql-mcp-server": {
"disabled": false,
"timeout": 60,
"type": "stdio",
"command": "uv",
"args": [
"tool",
"run",
"--from",
"awslabs.aurora-dsql-mcp-server@latest",
"awslabs.aurora-dsql-mcp-server.exe"
],
"env": {
"FASTMCP_LOG_LEVEL": "ERROR",
"AWS_PROFILE": "your-aws-profile",
"AWS_REGION": "us-east-1"
}
}
}
}
```
#### 查找 MCP 客户端配置文件
对于一些最常见的代理式开发工具，您可以在以下文件路径中找到 MCP 客户端配置：
+ Kiro：
+ 用户配置：`~/.kiro/settings/mcp.json`
+ 工作区配置：`/path/to/workspace/.kiro/settings/mcp.json`
+ Claude Code：有关详细的设置帮助，请参阅 [Claude 代码安装](#claude-code)
+ 用户配置：`"mcpServers"` 中的 `~/.claude.json`
+ 项目配置：`/path/to/project/.mcp.json`
+ 本地配置：`"projects" -> "path/to/project" -> "mcpServers"` 中的 `~/.claude.json`
+ 游标：
+ 全局：`~/.cursor/mcp.json`
+ 项目：`/path/to/project/.cursor/mcp.json`
+ Codex：`~/.codex/config.toml`
+ 在配置文件中为每个 MCP 服务器配置了一个 `[mcp_servers.]` 表。请参阅[自定义 Codex 安装说明](#codex)
+ 包装：
+ 文件编辑：`~/.warp/mcp_settings.json`
+ 应用程序编辑器：`Settings > AI > Manage MCP Servers` 并粘贴 json
+ Amazon Q 开发者版 CLI：`~/.aws/amazonq/mcp.json`
+ Cline：通常是一个嵌套的 VS 代码路径，即 `~/.vscode-server/path/to/cline_mcp_settings.json`
### Claude Code
#### 先决条件
**重要：**MCP 服务器管理只能通过 Claude Code CLI 终端体验获得，而不是 VS Code 原生面板模式。
首先按照 Claude 的[原生安装建议流程](https://code.claude.com/docs/en/setup#native-install-recommended)安装 Claude Code CLI。
#### 选择正确的范围
Claude Code 提供 3 种不同的范围：本地（默认）、项目和用户，以及有关要根据凭证敏感度选择哪个范围和需要共享哪个范围的详细信息。有关更多详细信息，请参阅有关 [MCP Installation Scopes](https://code.claude.com/docs/en/mcp#mcp-installation-scopes) 的 Claude Code 文档。
1. **本地范围的**服务器代表默认配置级别，存储在项目路径的 `~/.claude.json` 下。它们**都是**您私有的，并且只能在当前项目目录中访问。这是创建 MCP 服务器时的默认 `scope`。
1. **项目范围的**服务器**支持团队协作**，但仍然只能在项目目录中访问。项目范围的服务器在项目的根目录中添加一个 `.mcp.json` 文件。此文件旨在签入版本控制，确保所有团队成员都能访问相同的 MCP 工具和服务。添加项目范围的服务器时，Claude Code 会自动使用适当的配置结构创建或更新此文件。
1. **用户范围的**服务器存储在 `~/.claude.json` 中并**提供跨项目的可访问性**，使它们可以在计算机上的所有项目中使用，同时**对您的用户账户保持私有**。
#### 使用 Claude CLI（建议）
使用交互式 `claude` CLI 会话可以改善故障排除体验，因此这是建议的路径。
```
claude mcp add amazon-aurora-dsql \
--scope [one of local, project, or user] \
--env FASTMCP_LOG_LEVEL="ERROR" \
-- uvx "awslabs.aurora-dsql-mcp-server@latest" \
--cluster_endpoint "[dsql-cluster-id].dsql.[region].on.aws" \
--region "[dsql cluster region, eg. us-east-1]" \
--database_user "[your-username]"
```
##### 故障排除：在不同的 AWS 账户上将 Claude 代码与 Bedrock 结合使用
如果您使用 Bedrock AWS 账户或与连接到 dsql 集群所需的配置文件不同的配置文件配置了 Claude Code，则需要提供其它环境参数：
```
--env AWS_PROFILE="[dsql profile, eg. default]" \
--env AWS_REGION="[dsql cluster region, eg. us-east-1]" \
```
#### 在配置文件中直接修改
Claude Code 需要字母数字命名，因此我们建议您为服务器命名：`aurora-dsql-mcp-server`。
##### 本地范围
更新项目特定的 `mcpServers` 字段内的 `~/.claude.json`：
```
{
"projects": {
"/path/to/project": {
"mcpServers": {}
}
}
}
```
##### 项目范围
更新 `mcpServers` 字段中的 `/path/to/project/root/.mcp.json`：
```
{
"mcpServers": {}
}
```
##### 用户范围
更新项目特定的 `mcpServers` 字段内的 `~/.claude.json`：
```
{
"mcpServers": {}
}
```
### Codex
#### 选项 1：Codex CLI
如果您安装了 Codex CLI，则可以使用 codex mcp 命令来配置 MCP 服务器。
```
codex mcp add amazon-aurora-dsql \
--env FASTMCP_LOG_LEVEL="ERROR" \
-- uvx "awslabs.aurora-dsql-mcp-server@latest" \
--cluster_endpoint "[dsql-cluster-id].dsql.[region].on.aws" \
--region "[dsql cluster region, eg. us-east-1]" \
--database_user "[your-username]"
```
#### 选项 2：config.toml
要对 MCP 服务器选项进行更精细的控制，可以手动编辑 `~/.codex/config.toml` 配置文件。在配置文件中为每个 MCP 服务器配置了一个 `[mcp_servers.]` 表。
```
[mcp_servers.amazon-aurora-dsql]
command = "uvx"
args = [
"awslabs.aurora-dsql-mcp-server@latest",
"--cluster_endpoint", ".dsql..on.aws",
"--region", "",
"--database_user", ""
]
[mcp_servers.amazon-aurora-dsql.env]
FASTMCP_LOG_LEVEL = "ERROR"
```
### 验证安装
对于 Amazon Q 开发者版 CLI、Kiro CLI、Claude CLI/TUI 或 Codex CLI/TUI，请运行 `/mcp` 以查看 MCP 服务器的状态。
对于 Kiro IDE，还可以导航到 Kiro 面板的 `MCP SERVERS` 选项卡，该选项卡显示了所有已配置的 MCP 服务器及其连接状态指示器。
## 服务器配置选项
### `--allow-writes`
默认情况下，dsql MCP 服务器不允许写入操作（“只读模式”）。在此模式下，任何对 transact 工具的调用都将失败。要使用 transact 工具，需通过传递 `--allow-writes` 参数来允许写入。
建议在连接到 DSQL 时使用最低权限访问原则。例如，用户应尽可能使用只读角色。只读模式采用最优客户端强制策略来拒绝变更。
### `--cluster_endpoint`
这是用于指定要连接到的集群的必需参数。这应是集群的完整端点，例如 `01abc2ldefg3hijklmnopqurstu.dsql.us-east-1.on.aws`
### `--database_user`
这是用于指定用来连接的用户的必需参数。例如，`admin` 或 `my_user`。请注意，您使用的 AWS 凭证必须具有以该用户身份登录的权限。有关在 DSQL 中设置和使用数据库角色的更多信息，请参阅[使用数据库角色和 IAM 角色](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/using-database-and-iam-roles.html)。
### `--profile`
您可以指定用于凭证的 AWS 配置文件。请注意，无法在 Docker 安装中使用此参数。
此外，还支持在 MCP 配置中使用 `AWS_PROFILE` 环境变量：
```
"env": {
"AWS_PROFILE": "your-aws-profile"
}
```
如果两者均未提供，则 MCP 服务器将默认使用 AWS 配置文件中的“default”配置文件。
### `--region`
这是用于指定 DSQL 数据库区域的必需参数。
### `--knowledge-server`
可选参数，用于指定 DSQL 知识工具（文档搜索、读取和建议）的远程 MCP 服务器端点。默认情况下，它是预配置的。
示例：
```
--knowledge-server https://custom-knowledge-server.example.com
```
**注意：**为了安全起见，请仅使用受信任的知识服务器端点。服务器应为 HTTPS 端点。
### `--knowledge-timeout`
可选参数，用于指定向知识服务器发出的请求的超时时间（以秒为单位）。
默认值：`30.0`
示例：
```
--knowledge-timeout 60.0
```
如果您在通过网速慢的网络访问文档时遇到超时，请增大此值。