easy-mysql-mcp

AI 어시스턴트가 안전하고 구조화된 도구 인터페이스를 통해 MySQL 데이터베이스를 검사하고 쿼리할 수 있게 해주는 경량 Model Context Protocol (MCP) 서버입니다.

이 프로젝트는 Node.js, TypeScript, 공식 MCP SDK 및 mysql2/promise를 사용합니다. stdio를 통해 실행되므로 Claude Desktop과 같은 MCP 클라이언트에서 직접 사용할 수 있습니다.

기능

• mysql2/promise 기반의 MySQL 연결 풀링

• 데이터 검색을 위한 읽기 전용 쿼리 도구

• 데이터 수정 문을 위한 실행 도구

• 테이블, 뷰, 인덱스 및 트리거를 위한 스키마 탐색 도구

• EXPLAIN을 통한 쿼리 계획 검사

• 현재 사용자 및 권한 검사

• 비-MCP 로그가 stdio 프로토콜을 오염시키지 않도록 하는 stdout 보호

요구 사항

• Node.js 18 이상

• npm

• 연결 가능한 MySQL 호환 데이터베이스

설치

npx를 사용하여 서버를 직접 실행합니다:

npx -y easy-mysql-mcp

저장소를 복제한 후 로컬 개발을 위해:

cd easy-mysql-mcp
npm install
npm run build

구성

환경 변수로 서버를 구성합니다. MCP 클라이언트 구성이나 로컬 .env 파일을 생성하여 제공할 수 있습니다.

.env 예시:

MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database

사용법

npx를 통해 패키지를 실행하도록 MCP 클라이언트를 구성합니다.

로컬 개발을 위해 먼저 TypeScript 소스를 빌드합니다:

npm run build

MCP 서버를 시작합니다:

npm start

서버는 stdio를 통해 통신하며 일반적으로 수동으로 실행되지 않고 MCP 클라이언트에 의해 시작됩니다.

Claude Desktop 예시

claude_desktop_config.json에 서버를 추가합니다:

{
  "mcpServers": {
    "easy-mysql-mcp": {
      "command": "npx",
      "args": ["-y", "easy-mysql-mcp"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

구성을 업데이트한 후 Claude Desktop을 다시 시작하십시오.

사용 가능한 도구

보안 참고 사항

• 어시스턴트에 필요한 최소 권한만 가진 전용 MySQL 사용자를 사용하십시오.

• 검사 및 보고만 필요한 경우 읽기 전용 데이터베이스 자격 증명을 사용하는 것이 좋습니다.

• mysql_execute는 데이터를 수정할 수 있으므로 주의해서 사용하십시오.

• .env 파일이나 실제 데이터베이스 자격 증명을 GitHub에 커밋하지 마십시오.

• 프로덕션 데이터에 대해 실행하기 전에 생성된 SQL을 검토하십시오.

개발

npm run dev

이 명령은 감시 모드에서 TypeScript를 실행합니다.

프로덕션 빌드를 생성하려면:

npm run build

프로젝트 구조

src/
  db.ts       MySQL pool and query helpers
  index.ts    MCP server and tool registration
  proxy.ts    stdout protection for stdio-based MCP transport

라이선스

ISC