# AWS ラボ Aurora DSQL MCP サーバー
Aurora DSQL 用の AWS ラボモデルコンテキストプロトコル (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 Config ファイルの更新
#### `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 Config ファイルの検索](#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`
+ Workspace 設定: `/path/to/workspace/.kiro/settings/mcp.json`
+ Claude Code: 詳細なセットアップヘルプについては、「[Claude Code のインストール](#claude-code)」を参照してください
+ ユーザー設定: `"mcpServers"` の `~/.claude.json`
+ プロジェクト設定: `/path/to/project/.mcp.json`
+ ローカル設定: `"projects" -> "path/to/project" -> "mcpServers"` の `~/.claude.json`
+ Cursor:
+ グローバル: `~/.cursor/mcp.json`
+ プロジェクト: `/path/to/project/.cursor/mcp.json`
+ Codex: `~/.codex/config.toml`
+ 各 MCP サーバーは、設定ファイル内の `[mcp_servers.]` テーブルを使用して設定されます。「[カスタムコーデックのインストール手順](#codex)」を参照してください
+ Warp:
+ ファイルの編集: `~/.warp/mcp_settings.json`
+ アプリケーションエディタ: `Settings > AI > Manage MCP Servers` を選択し JSON を貼り付ける
+ Amazon Q Developer CLI: `~/.aws/amazonq/mcp.json`
+ Cline: 通常、ネストされた VS Code パス - `~/.vscode-server/path/to/cline_mcp_settings.json`
### Claude Code
#### 前提条件
**重要:** MCP サーバー管理は、VS Code ネイティブパネルモードではなく Claude Code CLI ターミナルエクスペリエンスを通じてのみ使用できます。
最初に、Claude の[ネイティブインストール推奨プロセス](https://code.claude.com/docs/en/setup#native-install-recommended)に従って、Claude Code CLI をインストールします。
#### 適切なスコープの選択
Claude Code は、ローカル (デフォルト)、プロジェクト、ユーザーという 3 つの異なるスコープを提供し、認証情報の機密性と共有の必要性に基づいてどのスコープを選択するかを詳細に説明しています。詳細については、[MCP インストールスコープ](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 アカウントの Bedrock と Claude Code を使用する
Claude Code を、dsql クラスターへの接続に必要なプロファイルとは異なる Bedrock AWS アカウントまたはプロファイルで設定した場合は、追加の環境引数を指定する必要があります。
```
--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 Developer CLI、Kiro CLI、Claude CLI/TUI、または Codex CLI/TUI の場合は、`/mcp` を実行して MCP サーバーのステータスを確認します。
Kiro IDE の場合、Kiro パネルの `MCP SERVERS` タブに移動して、設定されているすべての MCP サーバーとその接続ステータスインジケータを表示することもできます。
## サーバー設定オプション
### `--allow-writes`
デフォルトでは、dsql MCP サーバーは書き込みオペレーション (「読み取り専用モード」) を許可しません。トランザクションツールの呼び出しは、このモードでは失敗します。トランザクションツールを使用するには、`--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 設定ファイルの「デフォルト」プロファイルを使用します。
### `--region`
これは、DSQL データベースのリージョンを指定するための必須パラメータです。
### `--knowledge-server`
DSQL ナレッジツール (ドキュメント検索、読み取り、レコメンデーション) のリモート MCP サーバーエンドポイントを指定するオプションのパラメータ。デフォルトでは、事前設定されています。
例:
```
--knowledge-server https://custom-knowledge-server.example.com
```
**注:** セキュリティのため、信頼できるナレッジサーバーエンドポイントのみを使用してください。サーバーは HTTPS エンドポイントである必要があります。
### `--knowledge-timeout`
ナレッジサーバーへのリクエストのタイムアウトを秒単位で指定するオプションのパラメータ。
デフォルト: `30.0`
例:
```
--knowledge-timeout 60.0
```
低速ネットワークでドキュメントにアクセスするときにタイムアウトが発生した場合は、この値を増やします。