Berth -- 데이터베이스 MCP 서버

데이터를 위한 안전한 정박지 -- AI 도구를 위한 데이터베이스 액세스.

Berth는 AI 어시스턴트에게 PostgreSQL, SQLite 및 MySQL 데이터베이스에 대한 안전하고 구조화된 액세스 권한을 제공하는 Model Context Protocol 서버입니다. 스키마 검사, 쿼리 실행, 데이터 관리, 마이그레이션 생성 및 백업 수행을 위한 13가지 도구를 제공하며, 이 모든 것은 실수로 인한 손상을 방지하는 3단계 안전 모델에 의해 관리됩니다.

안전 모델

Berth는 허용되는 SQL을 제어하는 세 가지 운영 모드를 적용합니다:

서버는 read-only 모드로 시작합니다. 쓰기 및 관리자 모드는 명시적으로 활성화해야 합니다. 관리자 모드에서의 파괴적인 작업은 60초 후에 만료되는 일회성 확인 토큰을 생성하며, AI는 의도를 확인하기 위해 토큰을 다시 입력해야 합니다.

도구

스키마 마이그레이션

generate_migration 도구는 두 스키마를 비교하여 하나에서 다른 하나로 마이그레이션하기 위한 다이얼렉트 인식 SQL을 생성합니다. 두 가지 운영 모드가 있습니다:

모드 1 — 라이브 데이터베이스 vs. 대상 DDL:

connection_id(활성 연결)와 target_sql(원하는 스키마를 설명하는 CREATE TABLE 문)을 제공합니다. Berth는 라이브 데이터베이스를 내부적으로 검사하고 파싱된 대상과 비교합니다.

모드 2 — 두 개의 라이브 데이터베이스:

from_connection과 to_connection(두 개의 활성 연결 ID)을 제공합니다. Berth는 둘 다 내부적으로 검사하고 소스를 대상으로 변환하기 위한 마이그레이션을 생성합니다.

생성 내용:

• 새 테이블에 대한 CREATE TABLE

• 새 컬럼에 대한 ALTER TABLE ADD COLUMN

• 유형, null 허용 여부 및 기본값 변경을 위한 ALTER TABLE ALTER COLUMN / MODIFY COLUMN

• 인덱스 변경을 위한 CREATE INDEX / DROP INDEX

• 외래 키 변경을 위한 ADD CONSTRAINT / DROP CONSTRAINT

• DROP TABLE 및 DROP COLUMN은 경고와 함께 주석 처리됨 (안전 우선)

다이얼렉트 처리:

• PostgreSQL -- ALTER COLUMN ... TYPE, SET/DROP NOT NULL, SET/DROP DEFAULT 사용

• MySQL -- 모든 컬럼 변경에 MODIFY COLUMN, DROP INDEX ... ON table 사용

• SQLite -- 지원되지 않는 작업에 대해 경고하고, 이를 필요로 하는 변경 사항(ALTER COLUMN, 이전 버전에서의 DROP COLUMN, 제약 조건 변경)에 대해 테이블 재구축 패턴을 포함함

지원되는 데이터베이스

• PostgreSQL -- pg_stat_activity, EXPLAIN ANALYZE, pg_dump/psql 백업/복원을 포함한 전체 지원

• SQLite -- PRAGMA 내부 검사, sqlite3 CLI를 통한 .backup/.restore를 포함한 전체 지원

• MySQL -- information_schema 내부 검사, mysqldump/mysql 백업/복원을 포함한 전체 지원

설치

PyPI에서:

pip install berth-mcp

또는 격리된 환경에서:

pipx install berth-mcp

MySQL 지원은 선택적 종속성이 필요합니다:

pip install berth-mcp[mysql]

PostgreSQL(asyncpg) 및 SQLite(aiosqlite) 드라이버는 기본적으로 포함되어 있습니다.

사용법

서버 실행:

berth

Berth는 MCP 프로토콜을 사용하여 stdio를 통해 통신합니다. 독립 실행형이 아닌 MCP 클라이언트에 의해 실행되도록 설계되었습니다.

Claude Code

claude mcp add berth -- berth

Claude Desktop

claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "berth": {
      "command": "berth",
      "args": []
    }
  }
}

가상 환경에 설치된 경우 전체 경로를 사용하세요:

{
  "mcpServers": {
    "berth": {
      "command": "/path/to/venv/bin/berth",
      "args": []
    }
  }
}

환경 변수

보안

• 3단계 안전 모델 -- 기본적으로 읽기 전용, 쓰기는 명시적 동의 필요, 파괴적인 작업은 확인 토큰 필요

• 확인 토큰 -- DROP, TRUNCATE, ALTER DROP 및 전체 테이블 DELETE에 대해 60초 만료되는 일회성 UUID

• SQL 인젝션 보호 -- PRAGMA 문에서 사용하기 전에 sqlite_master를 기준으로 테이블 이름 검증; 전체적으로 매개변수화된 쿼리 사용

• 경로 탐색 보호 -- 백업/복원 경로는 BERTH_BACKUP_DIR 내에 유지되도록 확인 및 검증됨; null 바이트 거부

• 비밀번호 마스킹 -- DSN 비밀번호는 모든 표시 출력 및 오류 메시지에서 마스킹됨

개발

git clone https://github.com/seayniclabs/berth.git
cd berth
python -m venv .venv && source .venv/bin/activate
pip install -e ".[test]"
python -m pytest tests/ -q

PostgreSQL 및 MySQL에 대한 통합 테스트는 Docker가 필요합니다:

docker compose -f tests/docker-compose.test.yml up -d
python -m pytest tests/ -q
docker compose -f tests/docker-compose.test.yml down

라이선스

MIT