mysql-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

프로젝트 개요

MySQL 데이터베이스에 접근하기 위한 읽기 전용 MCP(Model Context Protocol) 서버. NPM 패키지로 배포됨 (@ahngbeom/mysql-mcp-server).

빌드 및 실행

npm run build    # TypeScript → JavaScript (dist/)
npm run dev      # 개발 모드 (tsx로 직접 실행)
npm start        # 빌드된 서버 실행

로컬 테스트

# 환경변수 설정 후 개발 모드로 실행
MYSQL_HOST=localhost MYSQL_PORT=3306 MYSQL_USER=root MYSQL_PASS=password MYSQL_DB=testdb npm run dev

MCP 서버는 stdio 통신을 사용하므로 직접 테스트하려면 JSON-RPC 메시지를 stdin으로 전송해야 함.

아키텍처

단일 파일 구조 (src/index.ts):

┌─────────────────────────────────────────────────────────┐
│  MCP Server (@modelcontextprotocol/sdk)                 │
│  ├── Tool Handlers (6개 도구)                            │
│  │   └── query, list_tables, describe_table,            │
│  │       show_indexes, show_create_table, explain       │
│  └── Resource Handlers (테이블별 스키마/샘플 데이터)        │
├─────────────────────────────────────────────────────────┤
│  Connection Pool (mysql2/promise, 최대 5 연결)           │
└─────────────────────────────────────────────────────────┘

쿼리 보안

중요: src/index.ts:160-177에서 읽기 전용 검증 수행

const allowedPrefixes = ["select", "show", "describe", "explain"];
const isReadOnly = allowedPrefixes.some(prefix => trimmedSql.startsWith(prefix));

• 허용: SELECT, SHOW, DESCRIBE, EXPLAIN
• 차단: INSERT, UPDATE, DELETE, DROP, CREATE, ALTER 등

수정 시 보안 우회가 발생하지 않도록 주의 (예: 주석, 서브쿼리 등으로 우회 시도 가능성 검토).

환경 변수

변수	기본값	설명
MYSQL_HOST	localhost	MySQL 호스트
MYSQL_PORT	3306	MySQL 포트
MYSQL_USER	root	사용자
MYSQL_PASS	(없음)	비밀번호
MYSQL_DB	mysql	데이터베이스