database-mcp

SQL 데이터베이스 MCP 서버로, 진정한 서버 측 결과 페이징을 지원합니다 — 기존의 어떤 데이터베이스 MCP 서버도 갖추지 못한 기능입니다 (DBHub는 행 수를 제한하고, Google의 MCP Toolbox는 모든 것을 반환하며, mcp-alchemy는 4000자에서 잘라냅니다).

PostgreSQL 참조 구현입니다.

왜 필요한가

기존의 모든 SQL MCP 서버는 대용량 결과를 잘라내거나 전체를 모델의 컨텍스트에 던져 넣습니다. MCP 사양은 목록 연산(tools/list)만 페이징할 뿐, 도구 결과는 페이징하지 않습니다. database-mcp가 그 격차를 메웁니다:

• 쿼리는 보류된 트랜잭션 내에서 PostgreSQL 서버 측 커서(DECLARE/FETCH FORWARD)로 한 번만 실행됩니다.

• 각 fetch(cursor)는 마지막 페이지가 끝난 정확히 그 지점에서 계속됩니다 — 재실행 없음, OFFSET 재스캔 없음, MVCC 스냅샷이 동시 쓰기 상황에서도 결과를 안정적으로 유지합니다.

• 페이지는 행 수(page_size) 그리고 렌더링된 바이트(max_page_bytes)로 제한됩니다. 크기가 큰 셀은 명시적 표시와 함께 잘립니다.

• 보류된 커서는 제한됩니다: 최대 N개 동시( LRU 축출), TTL 유휴 축출, 그리고 서버 측 백스톱으로 idle_in_transaction_session_timeout이 있습니다. 소진된 커서는 자동으로 닫힙니다.

Related MCP server: pgsql-mcp

연결 프로필 — 런타임에 AI가 관리

연결은 명명된 프로필로, ~/.config/database-mcp/profiles.json(chmod 600)에 저장됩니다. AI는 도구를 통해 서버 재시작 없이 즉시 프로필을 추가, 변경, 테스트, 제거할 수 있습니다:

• profile_add(name, dsn, allow_writes=false, description, make_default, test=true)

• profile_remove(name) · profile_test(name) · profiles()

• 모든 쿼리 도구는 선택적 profile 매개변수를 받습니다. 생략하면 기본 프로필이 사용됩니다.

프로필은 기본적으로 읽기 전용입니다(세션 수준 default_transaction_read_only). 쓰기에는 명시적 allow_writes=true 프로필이 필요합니다.

SSH 브리징

프로필은 SSH로만 접근 가능한 데이터베이스에 도달할 수 있습니다(전형적인 "Postgres가 원격 호스트의 localhost에서 수신 대기" 설정):

profile_add(name="prod", dsn="postgresql://app@dbhost:5432/app",
            ssh_host="dbhost")

• 터널은 시스템 ssh 하위 프로세스입니다(-N -L, BatchMode, keepalives) — ~/.ssh/config, 키, 에이전트가 변경 없이 적용됩니다. 인증은 비대화형으로 작동해야 합니다.

• ssh_remote_host/ssh_remote_port는 기본적으로 SSH 호스트 에서 본 DSN의 호스트/포트로 설정됩니다. DSN 호스트가 SSH 호스트와 같으면 127.0.0.1로 기본 설정됩니다(일반적인 경우).

• 터널은 지연 시작되며, 사용할 때마다 상태가 점검되고, 자동으로 재구축됩니다. 페이징 중에 터널이 죽으면 해당 커서는 명확한 오류와 함께 무효화되고 다음 쿼리가 재연결됩니다.

• 멀티플렉싱(ControlMaster)은 터널 연결에 대해 명시적으로 비활성화되어 터널의 수명이 정확히 하위 프로세스의 수명과 일치합니다.

도구

결과는 컴팩트 JSON입니다 — 열은 한 번, 행은 배열로 — 다른 서버가 내보내는 행-딕셔너리 형식보다 토큰이 약 절반입니다. query는 또한 estimated_rows( EXPLAIN을 통한 플래너 추정치)를 반환하므로 모델이 무엇을 페이징하고 있는지 알 수 있습니다.

설치 및 실행

uv pip install -e .
database-mcp --dsn postgresql://user@host:5432/db      # registers profile "default"
database-mcp                                           # start empty, add profiles at runtime

Claude Code 등록:

claude mcp add database -- database-mcp --dsn postgresql://user@host:5432/db

옵션: --profiles FILE, --allow-writes, --page-size 50, --max-page-size 500, --max-page-bytes 32000, --max-cell 400, --cursor-ttl 300, --max-cursors 4, --statement-timeout 30, --keepalive 120, --connect-timeout 5. 환경 변수: DATABASE_MCP_DSN / DATABASE_URL, DATABASE_MCP_PROFILES.

오래된 연결 처리

죽은 연결은 대기하지 않고 모든 계층에서 빠르게 감지됩니다:

• SSH 터널: ServerAliveInterval = --keepalive(기본 2분) 및 ServerAliveCountMax=1 — 한 번의 놓친 프로브가 터널 프로세스를 종료하고, 엔진 관리자가 다음 사용 시 이를 감지하고 지연 재구축합니다.

• DB 연결: TCP keepalives(keepalives_idle = --keepalive, 10초마다 프로브, 3회 실패)가 약 30초 내에 죽은 피어를 감지합니다 — 풀 외부의 고정된 커서 연결도 포함합니다.

• 풀 체크아웃 검사: 모든 연결은 저렴한 왕복으로 검증됩니다. 오래된 연결은 폐기되고 투명하게 교체됩니다 — 호출자는 오류를 볼 수 없습니다. 유휴 풀 연결은 --keepalive초 후 재활용됩니다. 연결 시도는 TCP 기본값 약 2분 대신 --connect-timeout(기본 5초) 후 실패합니다.

테스트

uv pip install -e '.[dev]'
pytest            # needs a local PostgreSQL (DBMCP_TEST_DSN to override)

라이선스

MIT