MCP Toolbox for Databases

왜 쓰나요

핵심 기능

단일 바이너리, 다양한 엔진 지원: Postgres, MySQL, BigQuery, Spanner, AlloyDB, Cloud SQL, SQLite, MSSQL, Redis, Couchbase, Dgraph, Neo4j
선언적 tools.yaml — 각 도구는 자유형 SQL 해치가 아닌 이름 붙은 파라미터화 구문
즉시 설정 없이 사용 가능한 사전 빌드 설정 (--prebuilt postgres)
커넥션 풀링과 인증(IAM, OAuth, API key)을 프롬프트가 아닌 중앙에서 처리
Stdio 또는 HTTP/SSE 전송 — Claude Desktop, Cursor, Codex, IDE, 커스텀 에이전트와 연동
도구별 권한 규칙 — 파괴적 구문을 호출할 수 있는 사용자를 제한

라이브 데모

실제 사용 모습

mcp-toolbox-databases.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-toolbox-databases": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcp-toolbox-databases",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "TOOLS_FILE=/config/tools.yaml",
        "-v",
        "${HOME}/.mcp-toolbox:/config",
        "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
        "--prebuilt",
        "postgres",
        "--stdio"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "mcp-toolbox-databases": {
      "command": {
        "path": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "TOOLS_FILE=/config/tools.yaml",
          "-v",
          "${HOME}/.mcp-toolbox:/config",
          "us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
          "--prebuilt",
          "postgres",
          "--stdio"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add mcp-toolbox-databases -- docker run -i --rm -e TOOLS_FILE=/config/tools.yaml -v ${HOME}/.mcp-toolbox:/config us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest --prebuilt postgres --stdio

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: MCP Toolbox for Databases

프로덕션 Postgres에 Claude가 안전하게 읽기 전용으로 접근하는 방법

👤 데이터 유출 위험 없이 LLM 분석을 원하는 백엔드/데이터 엔지니어 ⏱ ~25 min intermediate

언제 쓸까: DROP TABLE 가능한 범용 execute_sql 도구 없이 Claude가 실제 데이터베이스의 질문에 답하게 하고 싶을 때

사전 조건

libpq URL로 접근 가능한 Postgres — 읽기 전용 롤 사용; 앱의 쓰기 가능한 사용자는 절대 사용 금지
Docker 또는 Go 설치 — Toolbox는 단일 바이너리로 제공; Docker 이미지가 가장 간편

흐름

사전 빌드된 postgres 프로파일로 Toolbox 실행

읽기 복제본을 가리키는 POSTGRES_URL로 --prebuilt postgres를 사용하여 stdio 모드에서 mcp-toolbox를 시작하세요.✓ 복사됨

→ Toolbox 로그에 tools registered: list_tables, describe_table, execute_sql_readonly가 표시됨
Claude Desktop에 연결

toolbox docker 설정을 claude_desktop_config.json의 mcpServers에 추가한 후 Claude를 재시작하세요.✓ 복사됨

→ /mcp에 toolbox 도구 목록이 표시됨 — 실패 없음
실제 질문하기

Toolbox: 테이블 목록을 나열하세요. orders의 경우 최근 7일간 중앙값 주문금액은? 실행한 정확한 SQL을 보여주세요.✓ 복사됨

→ Claude가 list_tables → describe_table → execute_sql_readonly를 SELECT만으로 호출 (UPDATE/DELETE 없음)

결과: 변경 위험 없이 실제 데이터에 대한 읽기 전용 분석, 모든 쿼리의 감사 로그

함정

쓰기 가능한 사용자를 가리킬 경우 — Claude가 결국 변경 도구를 호출함 — GRANT SELECT만 있는 롤 사용; psql에서 \du로 확인
병렬 에이전트 호출로 커넥션 풀 소진 — tools.yaml에서 pool.max_open_conns 설정; 기본값은 보수적

함께 쓰기: filesystem · github

파라미터 유효성 검사가 있는 분석 도구 직접 작성

👤 원시 SQL이 아닌 승인된 쿼리만 원하는 팀 ⏱ ~20 min intermediate

언제 쓸까: Claude가 '이번 달 상위 10명의 고객'에 답하되 자체적으로 JOIN을 만들지 않게 하고 싶을 때

사전 조건

tools.yaml 파일 — ~/.mcp-toolbox/tools.yaml에 생성

흐름

파라미터화된 도구 작성

tools.yaml에 top_customers 도구 추가: 파라미터 since: date, 구문 SELECT customer_id, sum(total) FROM orders WHERE created_at >= $1 GROUP BY 1 ORDER BY 2 DESC LIMIT 10✓ 복사됨

→ Toolbox가 리로드되며 top_customers만 노출 — execute_sql_readonly 없음
Claude에서 호출

since=2026-04-01로 top_customers를 사용하고 결과를 설명하세요.✓ 복사됨

→ 유효성 검사된 날짜 파라미터로 단일 도구 호출, 형식화된 결과

결과: 잠긴 분석 인터페이스 — Claude는 당신이 선언한 것만 실행 가능

함정

사전 빌드된 execute_sql 도구 제거 忘忘 — --prebuilt 제거; tools.yaml만 로드

SQL 작성 없이 BigQuery 데이터셋 탐색

👤 Google Cloud의 분석가 ⏱ ~20 min intermediate

언제 쓸까: BigQuery 프로젝트가 있고 비용 가드레일을 적용하며 Claude가 질문에 답하게 하고 싶을 때

사전 조건

GCP 프로젝트 + 데이터셋 — Toolbox가 자격증명을 가져오도록 gcloud auth application-default login 실행

흐름

--prebuilt bigquery로 Toolbox 시작

PROJECT=my-proj로 --prebuilt bigquery toolbox를 실행하세요.✓ 복사됨

→ bq_list_datasets, bq_dry_run, bq_query 도구 등록됨
항상 dry-run 먼저

쿼리를 실행하기 전에 bq_dry_run을 호출하여 스캔할 바이트를 추정하세요. 1GB 초과 시 실행 전에 물어보세요.✓ 복사됨

→ 청구 가능한 쿼리 전에 비용 추정 표시

결과: 비용 가드레일이 있는 BigQuery 답변 — $200 짜리 놀라운 쿼리 없음

함정

기본 위치 불일치 (US vs EU) — BIGQUERY_LOCATION 환경 변수 설정

하나의 Claude 세션에서 여러 데이터베이스 쿼리

👤 크로스 스토어 이슈를 디버깅하는 엔지니어 ⏱ ~30 min advanced

언제 쓸까: 주문 데이터는 Postgres, 이벤트는 BigQuery, 캐시는 Redis에 있을 때 — 세 곳 모두에서 상관관계를 확인해야 할 때

사전 조건

여러 소스가 있는 tools.yaml — sources: 아래 각 소스를 정의하고 도구에 소스 태그 달기

흐름

세 소스 모두 연결

tools.yaml에 postgres-prod, bq-events, redis-cache를 소스로 추가하세요. 소스별로 도구를 1-2개씩 추가하세요.✓ 복사됨

→ Toolbox 시작, 모든 소스가 정상으로 표시됨
크로스 스토어 질문하기

주문 12345의 경우: Postgres에서 행을 가져오고, BigQuery에서 이벤트 타임라인을, Redis에서 현재 캐시 상태를 가져와 일치시키세요.✓ 복사됨

→ 세 개의 도구 호출이 팬아웃되어 단일한 일관된 답변

결과: 별도의 세 가지 도구나 SSH 세션 없이 크로스 스토어 디버깅

함정

소스 상태 확인이 자동으로 실패 — 시작하기 전에 toolbox validate tools.yaml 실행

함께 쓰기: filesystem

조합

다른 MCP와 조합해 10배 효율

mcp-toolbox-databases + filesystem

쿼리 결과를 가져와 워크스페이스의 CSV 파일에 저장

Toolbox: 이번 주 상위 100개 주문. Filesystem: /tmp/orders.csv로 저장.✓ 복사됨

mcp-toolbox-databases + github

Claude가 스키마 변경을 제안한 후 SQL 마이그레이션이 포함된 PR 열기

Toolbox: orders 테이블 설명. GitHub: customer_id에 인덱스를 추가하는 PR 열기.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
list_tables	schema?: str	첫 탐색 단계	1 query
describe_table	table: str	알 수 없는 테이블에 SQL을 작성하기 전에	1 query
execute_sql_readonly	sql: str	읽기 복제본에 대한 자유형 분석	1 query
bq_dry_run	sql: str	BigQuery: bq_query 전에 항상 실행	free (dry run)
bq_query	sql: str	dry run에서 허용 가능한 비용이 확인된 후	billable per bytes scanned
<your-custom-tool>	depends on tools.yaml	tools.yaml에서 선언한 모든 것	1 query

비용 및 제한

운영 비용

API 쿼터: 없음 — DB의 커넥션 상한선에 의해 제한
호출당 토큰: 결과 크기에 따라 100–5000
금액: 무료 OSS; 기반 DB/클라우드는 정상 청구
팁: tools.yaml에서 결과 행을 제한(예: LIMIT 200); BigQuery는 항상 bq_dry_run을 먼저 통과

보안

권한, 시크릿, 파급범위

최소 스코프: read-only DB role

자격 증명 저장: 환경 변수 또는 Google ADC; Toolbox는 자격증명을 절대 저장하지 않음

데이터 외부 송신: 직접 DB 연결 — 제3자 경유 없음. Toolbox는 로컬 전용.

절대 부여 금지: DBA DROP/TRUNCATE on prod

항상 읽기 복제본 + 읽기 전용 롤로 프로덕션을 앞에 놓기; 앱의 쓰기 가능한 사용자는 절대 사용 금지

문제 해결

자주 발생하는 오류와 해결

connection refused / 풀 소진

tools.yaml에서 pool.max_open_conns 증가; DB 커넥션 제한 확인

확인: psql, SELECT count(*) FROM pg_stat_activity 실행

tool not found

--prebuilt 사용 시 도구 이름은 예를 들어 pg_list_tables; toolbox list-tools 확인

BigQuery 403 접근 거부

gcloud auth application-default login 실행 및 roles/bigquery.dataViewer 부여

확인: bq ls

Spanner Cloud SDK 오류

GOOGLE_APPLICATION_CREDENTIALS를 서비스 계정 JSON으로 설정

대안