db-mcp-server

로컬 MCP 서버로, AI 코딩 어시스턴트(예: Claude Code)에게 PostgreSQL 데이터베이스에 대한 자격 증명 격리 액세스를 제공합니다. 어시스턴트는 SQL만 보내고 행만 받습니다. 데이터베이스 사용자 이름, 비밀번호, SSH 키는 모델의 컨텍스트나 대화 기록에 절대 들어가지 않습니다.

이유

AI 어시스턴트를 데이터베이스에 연결하려면 일반적으로 연결 문자열과 비밀번호를 모델(및 해당 기록)이 읽을 수 있는 곳에 두어야 합니다. 이 서버는 그 경계를 유지합니다. 암호화된 자격 증명과 SSH 터널을 소유하고, SQL 전용의 작은 도구 표면을 노출하며, 기본적으로 읽기 전용입니다.

Related MCP server: Postgres Scout MCP

작동 방식

• 카탈로그 (registry.yaml) — 비밀 아닌 라우팅. customers → environments → services로 구성됩니다. 각 서비스는 데이터베이스 이름과 secret_ref(볼트에 대한 포인터 — 자격 증명이 아님)에 매핑됩니다.

• 볼트 (vault.enc) — scrypt 파생 키를 사용하는 AES-256-GCM. DB 자격 증명을 보관하며, 시작 시 암호를 사용하여 한 번 메모리에 해독됩니다.

• 터널 풀 — sshtunnel을 통한 (customer, environment)당 하나의 SSH 터널, 임시 127.0.0.1 포트에 바인딩됩니다.

• 실행기 — psycopg. run_query는 Postgres READ ONLY 트랜잭션에서 실행됩니다(엔진이 모든 쓰기를 거부). run_write_query는 confirm=true가 필요합니다.

설치

python -m venv .venv
# Windows PowerShell: .venv\Scripts\Activate.ps1   (bash: source .venv/Scripts/activate)
pip install -e ".[dev]"

구성

구성은 환경 변수에서 가져옵니다. 기본값은 프로젝트 루트를 기준으로 확인됩니다.

프로비저닝(최초 설정)

1. 템플릿을 복사하고 실제 값을 채웁니다.

   cp bootstrap.example.yaml bootstrap.yaml

2. SSH 개인 키를 keys/에 넣습니다(파일 이름은 카탈로그의 pem_key 필드와 일치해야 합니다).

3. 비밀 아닌 카탈로그와 암호화된 볼트를 생성합니다(서버 실행 시 재사용할 암호를 묻습니다).

   python -m db_mcp_server.bootstrap --dry-run   # preview, writes nothing
   python -m db_mcp_server.bootstrap             # writes registry.yaml + vault.enc
   python -m db_mcp_server.vault_admin verify     # expect {"ok": true}

bootstrap.yaml은 평문 자격 증명을 보관합니다. git-ignored이며, 볼트가 생성되면 삭제하거나 오프라인으로 보관하세요.

명령줄 도구

(콘솔 명령은 pip install -e . 후에 사용할 수 있습니다. python -m db_mcp_server.<module> 형식은 항상 작동합니다.)

어시스턴트에 노출되는 도구

• list_databases() — 카탈로그(customers → environments → services); 비밀 없음.

• run_query(customer, environment, service, sql, max_rows?) — 읽기 전용.

• run_write_query(customer, environment, service, sql, confirm) — 게이트된 쓰기.

도메인 실패는 예외가 아닌 구조화된 {error_code, message}로 반환되므로 어시스턴트가 대응할 수 있습니다.

MCP 클라이언트에 등록

예시 .mcp.json(경로 조정). ${DB_MCP_PASSPHRASE}를 사용하여 암호가 파일에 기록되지 않고 셸에서 읽히도록 합니다.

{
  "mcpServers": {
    "db": {
      "command": "/absolute/path/to/db-mcp-server/.venv/Scripts/python.exe",
      "args": ["-m", "db_mcp_server.server"],
      "env": {
        "DB_MCP_PASSPHRASE": "${DB_MCP_PASSPHRASE}"
      }
    }
  }
}

보안 참고 사항

• vault.enc, keys/, bootstrap.yaml, *.env, *.pem은 git-ignored입니다. 절대 커밋하지 마세요.

• 볼트 암호는 DB_MCP_PASSPHRASE(또는 프롬프트)를 통해 제공됩니다. registry.yaml, argv, 로그에 저장하지 마세요.

• db-vault는 DB 비밀번호를 숨겨진 프롬프트(getpass)로 읽으며, argv를 사용하지 않습니다.

• run_query는 Postgres 엔진 수준에서 읽기 전용입니다. 쓰기에는 confirm=true가 필요합니다.

테스트

pip install -e ".[dev]" && python -m pytest -q

DB 통합 테스트는 DB_MCP_TEST_DSN이 연결 가능한 PostgreSQL을 가리키는 경우에만 실행됩니다.

로드맵(이 빌드에는 없음)

영구 감사 추적, 다중 사용자 운영, 외부 비밀 관리자 백엔드, 스키마 검사 도구, 자격 증명 격리를 하드 경계로 만드는 권한 거부 목록.