mcp-devdb

로컬 개발 데이터베이스를 위한 안전한 읽기 전용 MCP 서버입니다. 코딩 에이전트는 스키마, 샘플 데이터, 쿼리 계획, 테이블 크기 등 개발 데이터베이스를 지속적으로 확인해야 하지만, 단순한 데이터베이스 커넥터는 전체 쓰기 권한을 부여합니다. mcp-devdb는 강화된 읽기 전용 SQL 가드, 컬럼 마스킹, 결과 상한, 세션별 쿼리 예산 뒤에 인트로스펙션 도구를 노출하는 Model Context Protocol 서버로, 안전한 대안을 제공합니다.

v1의 백엔드: PostgreSQL (postgres 기반) 및 SQLite (better-sqlite3 기반). 어댑터 인터페이스는 엔진 중립적이므로 나중에 MySQL을 추가할 수 있습니다.

빠른 시작

1. 서버가 실행될 위치에 mcp-devdb.json을 생성합니다 (mcp-devdb.example.json 참조):

{
  "databases": {
    "app": { "url": "postgres://dev:dev@localhost:5432/app_development" },
    "cache": { "url": "sqlite:./data/cache.db" }
  }
}

2. 실행합니다:

npx mcp-devdb --config ./mcp-devdb.json

서버는 stdio를 통해 MCP를 사용합니다. MCP 클라이언트를 해당 명령에 연결하세요. 연결 문자열은 오직 구성 파일 또는 환경 변수에만 존재합니다 ("url": "env:MY_DB_URL", 또는 구성 파일이 없는 경우 MCP_DEVDB_URL 폴백) — 모델은 절대 제공할 수 없습니다.

Claude Code

claude mcp add devdb -- npx mcp-devdb --config /absolute/path/to/mcp-devdb.json

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "devdb": {
      "command": "npx",
      "args": ["mcp-devdb", "--config", "/absolute/path/to/mcp-devdb.json"]
    }
  }
}

Related MCP server: MCP PostgreSQL

도구

database는 정확히 하나의 데이터베이스가 구성된 경우 선택 사항입니다. 여러 개인 경우 원하는 것을 지정하세요.

구성

작업 디렉터리의 mcp-devdb.json 또는 --config를 통한 임의 경로:

{
  "databases": {
    "app": {
      "url": "postgres://dev:dev@localhost:5432/app_development",
      "allowTables": ["users", "orders", "public.events_*"],
      "denyTables": ["audit_log"]
    },
    "billing": { "url": "env:BILLING_DEV_DATABASE_URL" }
  },
  "maskPatterns": ["password", "secret", "token", "key", "hash", "ssn", "card"],
  "queryBudget": 100,
  "rowLimit": 200,
  "byteLimit": 262144,
  "statementTimeoutMs": 5000
}

• allowTables / denyTables — 대소문자 구분 없는 이름과 * 와일드카드; 점을 포함하는 규칙은 schema.table과 일치합니다. 거부가 우선하며, 비어 있지 않은 허용 목록은 배타적입니다.

• maskPatterns — 컬럼 이름에 대해 대소문자 구분 없는 정규식.

• CLI 플래그: --config <path>, --no-mask (컬럼 마스킹 비활성화), --help, --version.

보안 모델 (요약)

전체 위협 모델은 SECURITY.md에 있습니다. 간단히:

• 읽기 전용 가드: 모든 run_query/explain_query 문은 토큰화되고 (따옴표, E'...' 이스케이프, 주석, 달러 따옴표 문자열) SELECT / WITH / EXPLAIN / SHOW / VALUES로 시작해야 합니다. 다중 문 입력과 최상위 수준의 쓰기/DDL 키워드는 거부됩니다 — CTE 뒤에 INSERT가 오는 경우도 잡히며, SELECT 'DROP TABLE x'는 오탐이 아닙니다.

• 엔진 수준 강제: SQLite 파일은 읽기 전용으로 열립니다. PostgreSQL 세션은 default_transaction_read_only=on, 명시적 BEGIN READ ONLY 트랜잭션, 문 타임아웃으로 실행됩니다.

• 컬럼 마스킹 기본 활성화 (--no-mask로 해제), 결과 상한, 세션별 쿼리 예산 (기본 100; 소진 시 서버 재시작 안내).

• 자격 증명은 모델에 도달하지 않음: 연결 문자열은 로컬 구성/환경에서만 오며 모든 오류 메시지에서 제거됩니다.

스모크 테스트

scripts/verify-stdio.mjs는 임시 SQLite 데이터베이스를 만들고 node dist/cli.js를 실행한 후 stdio를 통해 실제 MCP 핸드셰이크를 원시 JSON-RPC로 구동합니다. 실제 출력:

$ node scripts/verify-stdio.mjs
initialize -> mcp-devdb 0.1.0 (protocol 2025-06-18)
tools/list -> db_overview, describe_table, explain_query, list_tables, run_query, sample_rows
tools/call list_tables ->
{
  "database": "demo",
  "dialect": "sqlite",
  "tableCount": 2,
  "tables": [
    {
      "schema": null,
      "name": "orders",
      "type": "table",
      "rowEstimate": 3,
      "sizeBytes": 4096,
      "sizePretty": "4.0 KiB"
    },
    {
      "schema": null,
      "name": "users",
      "type": "table",
      "rowEstimate": 2,
      "sizeBytes": 4096,
      "sizePretty": "4.0 KiB"
    }
  ]
}
tools/call run_query "DROP TABLE users" -> isError=true
  Query rejected by read-only guard: Only read-only statements are allowed; the statement must start with one of: SELECT, WITH, EXPLAIN, SHOW, VALUES
SMOKE TEST PASSED

제한 사항

• 아직 MySQL 없음. src/adapters/types.ts의 DbAdapter 인터페이스가 확장 지점입니다.

• 개발 데이터베이스 전용. 가드는 SQL 수준 쓰기를 차단하지만, SELECT는 잘못 레이블되거나 부작용이 있는 확장 함수를 호출할 수 있습니다 (예: dblink가 자체 비읽기 전용 연결을 여는 경우). 개발 데이터베이스에 대해서는 허용됩니다. 프로덕션에는 절대 사용하지 마세요. SECURITY.md 참조.

• 가드는 보수적입니다: 금지된 키워드와 같은 이름의 따옴표 없는 컬럼 (예: 문자 그대로 update라는 컬럼)은 거부됩니다 — 진행하려면 따옴표로 묶으세요 ("update").

• SELECT ... FOR UPDATE는 거부됩니다 (행 잠금을 획득하기 때문).

• SQLite 행 수는 COUNT(*)를 사용합니다. 거대한 파일에서는 list_tables가 느릴 수 있습니다.

개발

npm install
npm run lint && npm run typecheck && npm test && npm run build
node scripts/verify-stdio.mjs

라이선스

MIT — Copyright (c) 2026 Aminyx