sql-guard-mcp

English: README.en.md

AI 에이전트를 위한 읽기 전용 SQL — 다층 안전 가드 내장 MCP 서버.

LLM 에이전트에 DB를 그대로 열어주는 건 위험합니다. 이 서버는 SQLite를 4겹의 독립적인 가드 뒤에서 열어줍니다 — 에이전트가 할 수 있는 최악의 일이 "느리게 읽기"뿐이고, 그마저 상한에서 잘립니다.

이런 상황에서 씁니다

상황 — 광고 대행사. AE(기획자)는 SQL을 몰라서 "지난주 CTR 낮은 캠페인 좀 뽑아줘"를 매번 개발자에게 부탁하고, 개발자는 그때마다 쿼리를 짜 준다. 그렇다고 DB 계정을 열어주자니 실수로 지우거나 폭주 쿼리로 서비스에 영향을 줄까 무섭다.

도입 후 — Claude Desktop에 이 서버를 물리면 AE가 자연어로 직접 조회한다 — "지난주 CTR 최저 캠페인 5개 뽑아줘". 개발자는 허용 테이블 목록만 정해주면 되고, 쓰기·폭주·민감 테이블 접근은 코드가 막는다. 최악의 사고가 "느리게 읽기"뿐이라 안심하고 열어줄 수 있다.

동봉 데모 DB가 정확히 이 시나리오(광고 캠페인 성과)로 만들어져 있다.

Related MCP server: sqlite-analyst

가드 계층

설계 원칙은 실서비스 LLM 에이전트의 결정 가드를 만들며 얻은 것입니다. 모델이 조심하길 기대하지 말고, 부주의가 불가능하게 만들 것. 그리고 모든 거절 메시지는 에이전트에게 다음 행동을 알려줄 것.

도구

sql_list_tables · sql_describe_table · sql_query · sql_guard_status(현재 가드 설정 조회)

데모

Claude Desktop에 연결해 동봉된 광고 캠페인 데모 DB를 조회하고 — 삭제 요청은 거절하는 장면:

에이전트는 자유롭게 탐색·집계하지만("CTR이 가장 좋은 활성 캠페인은?"), campaigns 테이블을 지우라고 하면 가드가 거절하고 에이전트가 이유를 설명합니다 — 프롬프트가 아니라 코드가 강제하는 읽기 전용입니다.

설치

MCP SDK 외 의존성 없음 — 광고 캠페인 합성 데모 DB가 동봉되어 첫 실행 시 자동 생성됩니다.

pip install -e .

export SQLGUARD_DB="/path/to/your.db"                   # 기본: 동봉 데모
export SQLGUARD_ALLOWED_TABLES="campaigns,daily_stats"  # 기본: 전체 허용
export SQLGUARD_MAX_ROWS="200"

Claude Desktop 설정은 examples/ 참조. 설정 후 "지난주 CTR이 가장 좋았던 활성 캠페인은?"처럼 물으면 에이전트가 가드 안에서 스키마를 탐색하고 조회합니다. 삭제를 시켜보세요 — 거절 메시지를 읽어보시면 됩니다.

테스트

pip install -e ".[dev]"
pytest   # 29건 — 적대적 케이스 포함 (문장 이어붙이기, WITH 안의 DELETE, JOIN 허용 목록 우회, LIMIT 덮어쓰기, 폭주 조인 중단)

라이선스

MIT