db-mcp

읽기 전용 MCP 서버로, AI 에이전트가 작은 SQLite 쇼핑 데이터베이스(shop.db)에 안전하게 접근할 수 있게 해줍니다: 스키마 탐색, 자유 형식의 읽기 전용 SQL, 그리고 사전 구축된 분석 리포트를 제공합니다.

설치

npm install

Related MCP server: SQLite Read-Only MCP Server

구성

서버는 프로세스 환경에서 SHOP_DB_PATH를 읽어 데이터베이스 파일을 찾습니다. 이 값은 선택 사항입니다 — 설정하지 않으면 서버는 프로젝트 루트의 shop.db를 사용합니다. .env 파일은 자동으로 읽지 않습니다 (dotenv 의존성이 없고 package.json의 스크립트에 --env-file 플래그도 없습니다). .env.example은 단지 변수 이름을 알려주는 용도로만 제공됩니다. 서버가 실행되는 실제 환경에 SHOP_DB_PATH를 설정하세요 — stdio MCP 클라이언트의 경우, 이는 그 구성(config)의 env 키를 의미합니다 (아래 "클라이언트 연결" 참조).

빌드

npm run build

실행

npm start
# or directly:
node dist/index.js

서버는 stdio를 통해 MCP를 사용합니다 — MCP 클라이언트/호스트가 하위 프로세스로 실행해 주어야 하며, 대화형으로 실행되지 않습니다.

클라이언트 연결

일반적인 stdio MCP 클라이언트 구성:

{
  "mcpServers": {
    "db-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/db-mcp/dist/index.js"],
      "env": { "SHOP_DB_PATH": "/absolute/path/to/shop.db" }
    }
  }
}

Claude Desktop: claude_desktop_config.json의 mcpServers 아래에 동일한 블록을 추가하고(운영체제별 구성 파일 위치는 MCP.md 참고), Claude Desktop을 다시 시작하세요.

도구

보안 참고 사항

• 데이터베이스 연결은 { readonly: true, fileMustExist: true }로 열립니다 — SQLite 엔진 자체가 어떤 SQL을 보내든 물리적으로 쓰기를 거부합니다.

• query 도구는 입력이 데이터베이스에 도달하기 전에 단일 SELECT(또는 WITH ... SELECT) 문인지 추가로 검증하여, INSERT/UPDATE/DELETE/DROP/ALTER/CREATE/PRAGMA/ATTACH/DETACH/REPLACE/VACUUM/REINDEX/TRIGGER 및 다중 문장 입력 데이터를 친절한 오류 메시지와 함께 거부합니다.

• 각 도구의 경계에서 오류를 포착하여 isError: true와 짧은 메시지를 담은 MCP 도구 결과로 반환합니다 — 스택 트레이스나 파일시스템 경로는 절대 클라이언트로 보내지 않습니다.

• 모든 로그는 stderr(console.error)로 출력됩니다 — stdout은 오직 JSON-RPC 프로토콜 스트림 전용으로 예약되어 있습니다.

테스트

npm test

모든 *.test.ts 파일에 대해 node --test(tsx 사용)를 실행합니다: 실제 shop.db를 대상으로 SQL 가드, DB 연결, 각 도구의 쿼리 로직을 검증하는 단위 테스트와, 컴파일된 서버를 시작해 실제 MCP 클라이언트로 stdio를 통해 구동하는 종단 간 테스트가 포함됩니다.

Docker

docker build -t db-mcp .
docker run -i db-mcp

로컬에서 서버를 실행할 때는 필요하지 않지만(위의 클라이언트 구성은 로컬 node 프로세스를 전제로 합니다), 확인/실행을 위한 대안으로 제공됩니다.