# AWS Labs Aurora DSQL MCP 서버
Aurora DSQL용 AWS Labs Model Context Protocol(MCP) 서버
## 특성
+ 사람이 읽을 수 있는 질문과 명령을 구조화된 Postgres 호환 SQL 쿼리로 변환하고 구성된 Aurora DSQL 데이터베이스에 대해 실행합니다.
+ 기본적으로 읽기 전용, `--allow-writes`에서 활성화된 트랜잭션
+ 성능 향상을 위한 요청 간 연결 재사용
+ Aurora DSQL 설명서, 검색 및 모범 사례 권장 사항에 대한 기본 제공 액세스
## 사용 가능한 도구
### 데이터베이스 작업
+ **readonly\$1query** - DSQL 클러스터에 대해 읽기 전용 SQL 쿼리 실행
+ **트랜잭션** - 트랜잭션에서 쓰기 작업 실행(필수 `--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`
+ 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 설치 지침](#codex)을 참조하세요.
+ Warp:
+ 파일 편집: `~/.warp/mcp_settings.json`
+ 애플리케이션 편집기: `Settings > AI > Manage MCP Servers` 및 json 붙여넣기
+ Amazon Q Developer CLI: `~/.aws/amazonq/mcp.json`
+ Cline: 일반적으로 중첩된 VS 코드 경로 - `~/.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는 로컬(기본값), 프로젝트, 사용자라는 세 가지 범위를 제공하며, 자격 증명의 민감도와 공유 필요성에 따라 어떤 범위를 선택해야 하는지 자세히 설명합니다. 자세한 내용은 Claude Code 설명서의 [MCP 설치 범위](https://code.claude.com/docs/en/mcp#mcp-installation-scopes)를 참조하세요.
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 사용
dsql 클러스터에 연결하는 데 필요한 프로필과 구별되는 Bedrock AWS 계정 또는 프로필로 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 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
```
느린 네트워크의 설명서에 액세스할 때 제한 시간이 발생하면이 값을 늘립니다.