NodeJS 기반 MySQL용 MCP 서버

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

설치

대장간 사용

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

지엑스피1

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

올바른 환경 변수를 설정하세요
MCP 서버를 사용하도록 LLM 애플리케이션을 구성하세요.
MySQL 데이터베이스에 대한 연결을 테스트하세요
필요한 경우 유용한 문제 해결 방법을 제공합니다.

MCP Get 사용

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

npx @michaellatman/mcp-get@latest install @benborla29/mcp-server-mysql

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

NPM/PNPM 사용

수동 설치의 경우:

# Using npm
npm install -g @benborla29/mcp-server-mysql

# Using pnpm
pnpm add -g @benborla29/mcp-server-mysql

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

구성 요소

도구

mysql_쿼리
- 연결된 데이터베이스에 대해 읽기 전용 SQL 쿼리를 실행합니다.
- 입력: sql (문자열): 실행할 SQL 쿼리
- 모든 쿼리는 READ ONLY 트랜잭션 내에서 실행됩니다.
- 안전한 매개변수 처리를 위한 준비된 명령문 지원
- 구성 가능한 쿼리 시간 초과 및 결과 페이지 매김
- 내장된 쿼리 실행 통계

자원

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

테이블 스키마
- 각 테이블에 대한 JSON 스키마 정보
- 열 이름 및 데이터 유형
- 인덱스 정보 및 제약 조건
- 외래 키 관계
- 테이블 통계 및 메트릭
- 데이터베이스 메타데이터에서 자동으로 검색됨

보안 기능

준비된 명령문을 통한 SQL 주입 방지
화이트리스트/블랙리스트 기능 쿼리
쿼리 실행에 대한 속도 제한
쿼리 복잡도 분석
구성 가능한 연결 암호화
읽기 전용 거래 시행

성능 최적화

최적화된 연결 풀링
쿼리 결과 캐싱
대규모 결과 세트 스트리밍
쿼리 실행 계획 분석
구성 가능한 쿼리 시간 초과

모니터링 및 디버깅

포괄적인 쿼리 로깅
성능 지표 수집
오류 추적 및 보고
상태 점검 엔드포인트
쿼리 실행 통계

구성

Smithery를 사용한 자동 구성

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

smithery configure @benborla29/mcp-server-mysql

Claude 데스크톱 앱 수동 구성

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

{
  "mcpServers": {
    "mcp_server_mysql": {
      "command": "npx",
      "args": [
        "-y",
        "@benborla29/mcp-server-mysql"
      ],
      "env": {
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASS": "",
        "MYSQL_DB": "db_name"
      }
    }
  }
}

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

고급 구성 옵션

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

{
  "mcpServers": {
    "mcp_server_mysql": {
      "command": "/path/to/npx/binary/npx",
      "args": [
        "-y",
        "@benborla29/mcp-server-mysql"
      ],
      "env": {
        // Basic connection settings
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASS": "",
        "MYSQL_DB": "db_name",
        "PATH": "/path/to/node/bin:/usr/bin:/bin",
        
        // Performance settings
        "MYSQL_POOL_SIZE": "10",
        "MYSQL_QUERY_TIMEOUT": "30000",
        "MYSQL_CACHE_TTL": "60000",
        
        // Security settings
        "MYSQL_RATE_LIMIT": "100",
        "MYSQL_MAX_QUERY_COMPLEXITY": "1000",
        "MYSQL_SSL": "true",
        
        // Monitoring settings
        "MYSQL_ENABLE_LOGGING": "true",
        "MYSQL_LOG_LEVEL": "info",
        "MYSQL_METRICS_ENABLED": "true"
      }
    }
  }
}

환경 변수

기본 연결

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")

테스트

데이터베이스 설정

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

테스트 데이터베이스 및 사용자 생성
-- 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;
데이터베이스 설정 스크립트 실행
# Run the database setup script pnpm run setup:test:db
이렇게 하면 필요한 테이블과 시드 데이터가 생성됩니다. 스크립트는 scripts/setup-test-db.ts 에 있습니다.
테스트 환경 구성 프로젝트 루트에 .env.test 파일을 만듭니다.
MYSQL_HOST=127.0.0.1 MYSQL_PORT=3306 MYSQL_USER=mcp_test MYSQL_PASS=mcp_test_password MYSQL_DB=mcp_test
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" } }

테스트 실행

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

# First-time setup
pnpm run setup:test:db

# Run all tests
pnpm test

문제 해결

문제 해결을 위한 Smithery 사용

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

# Check the status of your MCP server
smithery status @benborla29/mcp-server-mysql

# Run diagnostics
smithery diagnose @benborla29/mcp-server-mysql

# View logs
smithery logs @benborla29/mcp-server-mysql

문제 해결을 위한 MCP Get 사용

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

# Check the status
mcp-get status @benborla29/mcp-server-mysql

# View logs
mcp-get logs @benborla29/mcp-server-mysql

일반적인 문제

연결 문제
- MySQL 서버가 실행 중이고 접근 가능한지 확인하세요.
- 자격 증명 및 권한 확인
- SSL/TLS 구성이 활성화된 경우 올바른지 확인하세요.
- MySQL 클라이언트에 연결하여 액세스를 확인해 보세요.
성능 문제
- 연결 풀 크기 조정
- 쿼리 시간 초과 값 구성
- 필요한 경우 쿼리 캐싱을 활성화하세요
- 쿼리 복잡성 설정 확인
- 서버 리소스 사용량 모니터링
보안 제한 사항
- 속도 제한 구성 검토
- 쿼리 허용 목록/차단 목록 설정 확인
- SSL/TLS 설정 확인
- 사용자에게 적절한 MySQL 권한이 있는지 확인하세요.
경로 해결 "MCP 서버 mcp-server-mysql에 연결할 수 없습니다" 오류가 발생하는 경우, 모든 필수 바이너리의 경로를 명시적으로 설정하세요.

{
  "env": {
    "PATH": "/path/to/node/bin:/usr/bin:/bin"
  }
}

인증 문제
- 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 에 풀 리퀘스트를 제출해 주세요.

개발 설정

저장소를 복제합니다
종속성 설치: pnpm install
프로젝트 빌드: pnpm run build
테스트 실행: pnpm test

프로젝트 로드맵

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

준비된 명령문을 통한 향상된 쿼리 기능
고급 보안 기능
성능 최적화
종합적인 모니터링
확장된 스키마 정보

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

변경 사항 제출

저장소를 포크하세요
기능 브랜치를 만듭니다: git checkout -b feature/your-feature-name
변경 사항을 커밋하세요: git commit -am 'Add some feature'
브랜치에 푸시: git push origin feature/your-feature-name
풀 리퀘스트 제출

특허

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

MCP Server for MySQL

Integrations