NodeJS 기반 MySQL용 MCP 서버

MySQL 데이터베이스에 대한 읽기 전용 액세스를 제공하는 모델 컨텍스트 프로토콜 서버입니다. 이 서버를 통해 LLM은 데이터베이스 스키마를 검사하고 읽기 전용 쿼리를 실행할 수 있습니다.

설치

대장간 사용

이 MCP 서버를 설치하고 구성하는 가장 쉬운 방법은 Smithery를 사용하는 것입니다.

지엑스피1

구성하는 동안 MySQL 연결 세부 정보를 입력하라는 메시지가 표시됩니다. Smithery는 자동으로 다음을 수행합니다.

• 올바른 환경 변수를 설정하세요

• MCP 서버를 사용하도록 LLM 애플리케이션을 구성하세요.

• MySQL 데이터베이스에 대한 연결을 테스트하세요

• 필요한 경우 유용한 문제 해결 방법을 제공합니다.

MCP Get 사용

MCP Get을 사용하여 이 패키지를 설치할 수도 있습니다.

MCP Get은 MCP 서버의 중앙 레지스트리를 제공하고 설치 과정을 간소화합니다.

NPM/PNPM 사용

수동 설치의 경우:

수동 설치 후 MCP 서버를 사용하도록 LLM 애플리케이션을 구성해야 합니다(아래 구성 섹션 참조).

구성 요소

도구

• mysql_쿼리

  • 연결된 데이터베이스에 대해 읽기 전용 SQL 쿼리를 실행합니다.

  • 입력: sql (문자열): 실행할 SQL 쿼리

  • 모든 쿼리는 READ ONLY 트랜잭션 내에서 실행됩니다.

  • 안전한 매개변수 처리를 위한 준비된 명령문 지원

  • 구성 가능한 쿼리 시간 초과 및 결과 페이지 매김

  • 내장된 쿼리 실행 통계

자원

서버는 포괄적인 데이터베이스 정보를 제공합니다.

• 테이블 스키마

  • 각 테이블에 대한 JSON 스키마 정보

  • 열 이름 및 데이터 유형

  • 인덱스 정보 및 제약 조건

  • 외래 키 관계

  • 테이블 통계 및 메트릭

  • 데이터베이스 메타데이터에서 자동으로 검색됨

보안 기능

• 준비된 명령문을 통한 SQL 주입 방지

• 화이트리스트/블랙리스트 기능 쿼리

• 쿼리 실행에 대한 속도 제한

• 쿼리 복잡도 분석

• 구성 가능한 연결 암호화

• 읽기 전용 거래 시행

성능 최적화

• 최적화된 연결 풀링

• 쿼리 결과 캐싱

• 대규모 결과 세트 스트리밍

• 쿼리 실행 계획 분석

• 구성 가능한 쿼리 시간 초과

모니터링 및 디버깅

• 포괄적인 쿼리 로깅

• 성능 지표 수집

• 오류 추적 및 보고

• 상태 점검 엔드포인트

• 쿼리 실행 통계

구성

Smithery를 사용한 자동 구성

Smithery를 사용하여 설치한 경우 구성이 이미 설정되어 있습니다. 다음을 사용하여 구성 내용을 확인하거나 수정할 수 있습니다.

Claude 데스크톱 앱 수동 구성

Claude Desktop App에 대한 MCP 서버를 수동으로 구성하려면 다음을 claude_desktop_config.json 파일(일반적으로 사용자 디렉토리에 있음)에 추가하세요.

db_name 데이터베이스 이름으로 바꾸거나 모든 데이터베이스에 액세스하려면 비워 두세요.

고급 구성 옵션

MCP 서버의 동작을 더 세밀하게 제어하려면 다음과 같은 고급 구성 옵션을 사용할 수 있습니다.

환경 변수

기본 연결

• MYSQL_HOST : MySQL 서버 호스트(기본값: "127.0.0.1")

• MYSQL_PORT : MySQL 서버 포트(기본값: "3306")

• MYSQL_USER : MySQL 사용자 이름(기본값: "root")

• MYSQL_PASS : MySQL 비밀번호

• MYSQL_DB : 대상 데이터베이스 이름

성능 구성

• MYSQL_POOL_SIZE : 연결 풀 크기(기본값: "10")

• MYSQL_QUERY_TIMEOUT : 쿼리 시간 초과(밀리초) (기본값: "30000")

• MYSQL_CACHE_TTL : 캐시 수명(밀리초)(기본값: "60000")

보안 구성

• MYSQL_RATE_LIMIT : 분당 최대 쿼리 수(기본값: "100")

• MYSQL_MAX_QUERY_COMPLEXITY : 최대 쿼리 복잡도 점수(기본값: "1000")

• MYSQL_SSL : SSL/TLS 암호화를 활성화합니다(기본값: "false")

모니터링 구성

• MYSQL_ENABLE_LOGGING : 쿼리 로깅을 활성화합니다(기본값: "false")

• MYSQL_LOG_LEVEL : 로깅 레벨(기본값: "info")

• MYSQL_METRICS_ENABLED : 성능 지표 활성화(기본값: "false")

테스트

데이터베이스 설정

테스트를 실행하기 전에 테스트 데이터베이스를 설정하고 테스트 데이터를 시드해야 합니다.

1. 테스트 데이터베이스 및 사용자 생성

   -- Connect as root and create test database CREATE DATABASE IF NOT EXISTS mcp_test; -- Create test user with appropriate permissions CREATE USER IF NOT EXISTS 'mcp_test'@'localhost' IDENTIFIED BY 'mcp_test_password'; GRANT ALL PRIVILEGES ON mcp_test.* TO 'mcp_test'@'localhost'; FLUSH PRIVILEGES;

2. 데이터베이스 설정 스크립트 실행

   # Run the database setup script pnpm run setup:test:db

   이렇게 하면 필요한 테이블과 시드 데이터가 생성됩니다. 스크립트는 scripts/setup-test-db.ts 에 있습니다.

3. 테스트 환경 구성 프로젝트 루트에 .env.test 파일을 만듭니다.

   MYSQL_HOST=127.0.0.1 MYSQL_PORT=3306 MYSQL_USER=mcp_test MYSQL_PASS=mcp_test_password MYSQL_DB=mcp_test

4. package.json 스크립트 업데이트 package.json에 다음 스크립트를 추가합니다.

   { "scripts": { "setup:test:db": "ts-node scripts/setup-test-db.ts", "pretest": "pnpm run setup:test:db", "test": "vitest run", "test:watch": "vitest", "test:coverage": "vitest run --coverage" } }

테스트 실행

이 프로젝트에는 기능성과 안정성을 보장하기 위한 포괄적인 테스트 모음이 포함되어 있습니다.

문제 해결

문제 해결을 위한 Smithery 사용

Smithery를 설치한 경우 내장된 진단 도구를 사용할 수 있습니다.

문제 해결을 위한 MCP Get 사용

MCP Get을 사용하여 설치한 경우:

일반적인 문제

1. 연결 문제

   • MySQL 서버가 실행 중이고 접근 가능한지 확인하세요.

   • 자격 증명 및 권한 확인

   • SSL/TLS 구성이 활성화된 경우 올바른지 확인하세요.

   • MySQL 클라이언트에 연결하여 액세스를 확인해 보세요.

2. 성능 문제

   • 연결 풀 크기 조정

   • 쿼리 시간 초과 값 구성

   • 필요한 경우 쿼리 캐싱을 활성화하세요

   • 쿼리 복잡성 설정 확인

   • 서버 리소스 사용량 모니터링

3. 보안 제한 사항

   • 속도 제한 구성 검토

   • 쿼리 허용 목록/차단 목록 설정 확인

   • SSL/TLS 설정 확인

   • 사용자에게 적절한 MySQL 권한이 있는지 확인하세요.

4. 경로 해결 "MCP 서버 mcp-server-mysql에 연결할 수 없습니다" 오류가 발생하는 경우, 모든 필수 바이너리의 경로를 명시적으로 설정하세요.

5. 인증 문제

   • MySQL 8.0 이상의 경우 서버가 caching_sha2_password 인증 플러그인을 지원하는지 확인하세요.

   • MySQL 사용자가 올바른 인증 방법으로 구성되었는지 확인하세요.

   • 필요한 경우 레거시 인증을 사용하여 사용자를 생성해보세요.

     CREATE USER 'user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';

기여하다

기여를 환영합니다! https://github.com/benborla/mcp-server-mysql 에 풀 리퀘스트를 제출해 주세요.

개발 설정

1. 저장소를 복제합니다

2. 종속성 설치: pnpm install

3. 프로젝트 빌드: pnpm run build

4. 테스트 실행: pnpm test

프로젝트 로드맵

현재 MCP 서버 개선을 위해 적극적으로 노력하고 있습니다. 계획된 기능에 대한 자세한 내용은 CHANGELOG.md를 참조하세요.

• 준비된 명령문을 통한 향상된 쿼리 기능

• 고급 보안 기능

• 성능 최적화

• 종합적인 모니터링

• 확장된 스키마 정보

이러한 분야에 기여하고 싶다면 GitHub에서 이슈를 확인하거나 새로운 이슈를 열어 아이디어에 대해 논의하세요.

변경 사항 제출

1. 저장소를 포크하세요

2. 기능 브랜치를 만듭니다: git checkout -b feature/your-feature-name

3. 변경 사항을 커밋하세요: git commit -am 'Add some feature'

4. 브랜치에 푸시: git push origin feature/your-feature-name

5. 풀 리퀘스트 제출

특허

이 MCP 서버는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 라이선스 파일을 참조하세요.