NodeJS 기반 MySQL용 MCP 서버

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

요구 사항

Node.js v18 이상
MySQL 5.7 이상(MySQL 8.0 이상 권장)
필요한 작업에 대한 적절한 권한이 있는 MySQL 사용자
쓰기 작업의 경우: INSERT, UPDATE 및/또는 DELETE 권한이 있는 MySQL 사용자

설치

MCP 서버를 설치하고 구성하는 방법에는 여러 가지가 있습니다.

클로드 데스크탑

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

지엑스피1

커서

Cursor IDE의 경우 다음 명령을 사용하여 프로젝트에 MCP 서버를 설치할 수 있습니다.

npx mcprunner MYSQL_HOST=127.0.0.1 MYSQL_PORT=3306 MYSQL_USER=root MYSQL_PASS=root MYSQL_DB=demostore ALLOW_INSERT_OPERATION=true ALLOW_UPDATE_OPERATION=true ALLOW_DELETE_OPERATION=false -- npx -y @benborla29/mcp-server-mysql

해당 명령의 env 값을 바꾸는 것을 잊지 마세요. Cursor 최신 버전(v0.47 이상)을 사용 중이라면 아래 설정을 복사하여 붙여넣으세요.

mcp.json

{
  "mcpServers": {
    "MySQL": {
      "command": "npx",
      "args": [
        "mcprunner",
        "MYSQL_HOST=127.0.0.1",
        "MYSQL_PORT=3306",
        "MYSQL_USER=root",
        "MYSQL_PASS=root",
        "MYSQL_DB=demostore",
        "ALLOW_INSERT_OPERATION=true",
        "ALLOW_UPDATE_OPERATION=true",
        "ALLOW_DELETE_OPERATION=false",
        "--",
        "npx",
        "-y",
        "@benborla29/mcp-server-mysql"
      ]
    }
  }
}

대장간 사용

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

npx -y @smithery/cli@latest install @benborla29/mcp-server-mysql --client claude

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

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

설치 과정에서 다음과 같은 연결 세부 정보를 입력하라는 메시지가 표시됩니다.

MySQL 호스트(기본값: 127.0.0.1)
MySQL 포트(기본값: 3306)
MySQL 사용자 이름
MySQL 비밀번호
MySQL 데이터베이스 이름
SSL 구성(필요한 경우)
쓰기 작업 권한:
- INSERT 작업 허용(기본값: false)
- UPDATE 작업 허용(기본값: false)
- DELETE 작업 허용(기본값: false)

보안상의 이유로 쓰기 작업은 기본적으로 비활성화되어 있습니다. Claude가 데이터베이스 데이터를 수정해야 하는 경우에만 활성화하세요.

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 애플리케이션을 구성해야 합니다(아래 구성 섹션 참조).

로컬 저장소에서 실행

소스 코드에서 직접 MCP 서버를 복제하고 실행하려면 다음 단계를 따르세요.

저장소를 복제합니다
git clone https://github.com/benborla/mcp-server-mysql.git cd mcp-server-mysql
종속성 설치
npm install # or pnpm install
프로젝트를 빌드하세요
npm run build # or pnpm run build
Claude Desktop 구성Claude Desktop 구성 파일( claude_desktop_config.json )에 다음을 추가합니다.
{ "mcpServers": { "mcp_server_mysql": { "command": "/path/to/node", "args": [ "/full/path/to/mcp-server-mysql/dist/index.js" ], "env": { "MYSQL_HOST": "127.0.0.1", "MYSQL_PORT": "3306", "MYSQL_USER": "root", "MYSQL_PASS": "your_password", "MYSQL_DB": "your_database", "ALLOW_INSERT_OPERATION": "false", "ALLOW_UPDATE_OPERATION": "false", "ALLOW_DELETE_OPERATION": "false", "PATH": "/Users/atlasborla/Library/Application Support/Herd/config/nvm/versions/node/v22.9.0/bin:/usr/bin:/bin", // <--- Important to add the following, run in your terminal `echo "$(which node)/../"` to get the path "NODE_PATH": "/Users/atlasborla/Library/Application Support/Herd/config/nvm/versions/node/v22.9.0/lib/node_modules" // <--- Important to add the following, run in your terminal `echo "$(which node)/../../lib/node_modules"` } } } }
바꾸다:
- /path/to/node 에 Node.js 바이너리의 전체 경로를 입력합니다( which node 로 검색).
- /full/path/to/mcp-server-mysql 저장소를 복제한 전체 경로를 입력합니다.
- 사용자 환경에 맞게 MySQL 자격 증명을 설정하세요.
서버 테스트
# Run the server directly to test node dist/index.js
MySQL에 성공적으로 연결되면 Claude Desktop과 함께 사용할 준비가 된 것입니다.

구성 요소

도구

mysql_쿼리
- 연결된 데이터베이스에 대해 SQL 쿼리를 실행합니다.
- 입력: sql (문자열): 실행할 SQL 쿼리
- 기본적으로 READ ONLY 작업으로 제한됩니다.
- 선택적 쓰기 작업(구성을 통해 활성화된 경우):
  - INSERT: 테이블에 새 데이터 추가( ALLOW_INSERT_OPERATION=true 필요)
  - 업데이트: 기존 데이터 수정( ALLOW_UPDATE_OPERATION=true 필요)
  - DELETE: 데이터 제거( ALLOW_DELETE_OPERATION=true 필요)
- 모든 작업은 적절한 커밋/롤백 처리를 통해 트랜잭션 내에서 실행됩니다.
- 안전한 매개변수 처리를 위한 준비된 명령문 지원
- 구성 가능한 쿼리 시간 초과 및 결과 페이지 매김
- 내장된 쿼리 실행 통계

자원

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

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

보안 기능

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

성능 최적화

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

모니터링 및 디버깅

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

구성

Smithery를 사용한 자동 구성

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

smithery configure @benborla29/mcp-server-mysql

재구성할 때 MySQL 연결 세부 정보와 쓰기 작업 설정을 모두 업데이트할 수 있습니다.

기본 연결 설정 :
- MySQL 호스트, 포트, 사용자, 비밀번호, 데이터베이스
- SSL/TLS 구성(데이터베이스에 보안 연결이 필요한 경우)
쓰기 작업 권한 :
- INSERT 작업 허용: 새 데이터 추가를 허용하려면 true로 설정합니다.
- UPDATE 작업 허용: 기존 데이터 업데이트를 허용하려면 true로 설정합니다.
- DELETE 작업 허용: 데이터 삭제를 허용하려면 true로 설정합니다.

보안상의 이유로 모든 쓰기 작업은 기본적으로 비활성화되어 있습니다. Claude가 데이터베이스 데이터를 수정해야 하는 경우에만 이 설정을 활성화하세요.

고급 구성 옵션

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",
        
        // Write operation flags
        "ALLOW_INSERT_OPERATION": "false",
        "ALLOW_UPDATE_OPERATION": "false",
        "ALLOW_DELETE_OPERATION": "false"
      }
    }
  }
}

환경 변수

기본 연결

MYSQL_HOST : MySQL 서버 호스트(기본값: "127.0.0.1")
MYSQL_PORT : MySQL 서버 포트(기본값: "3306")
MYSQL_USER : MySQL 사용자 이름(기본값: "root")
MYSQL_PASS : MySQL 비밀번호
MYSQL_DB : 대상 데이터베이스 이름(다중 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")
ALLOW_INSERT_OPERATION : INSERT 작업을 활성화합니다(기본값: "false")
ALLOW_UPDATE_OPERATION : UPDATE 작업을 활성화합니다(기본값: "false")
ALLOW_DELETE_OPERATION : DELETE 작업 활성화(기본값: "false")
ALLOW_DDL_OPERATION : DDL 작업 활성화(기본값: "false")
SCHEMA_INSERT_PERMISSIONS : 스키마별 INSERT 권한
SCHEMA_UPDATE_PERMISSIONS : 스키마별 UPDATE 권한
SCHEMA_DELETE_PERMISSIONS : 스키마별 DELETE 권한
SCHEMA_DDL_PERMISSIONS : 스키마별 DDL 권한
MULTI_DB_WRITE_MODE : 다중 DB 모드에서 쓰기 작업을 활성화합니다(기본값: "false")

모니터링 구성

MYSQL_ENABLE_LOGGING : 쿼리 로깅을 활성화합니다(기본값: "false")
MYSQL_LOG_LEVEL : 로깅 레벨(기본값: "info")
MYSQL_METRICS_ENABLED : 성능 지표 활성화(기본값: "false")

다중 DB 모드

MCP-Server-MySQL은 특정 데이터베이스가 설정되지 않은 경우 여러 데이터베이스에 대한 연결을 지원합니다. 이를 통해 LLM은 MySQL 사용자가 액세스 권한이 있는 모든 데이터베이스에 쿼리를 실행할 수 있습니다. 자세한 내용은 README-MULTI-DB.md를 참조하세요.

다중 DB 모드 활성화

다중 DB 모드를 활성화하려면 MYSQL_DB 환경 변수를 비워 두세요. 다중 DB 모드에서는 쿼리에 스키마 한정자가 필요합니다.

-- Use fully qualified table names
SELECT * FROM database_name.table_name;

-- Or use USE statements to switch between databases
USE database_name;
SELECT * FROM table_name;

스키마별 권한

데이터베이스 작업에 대한 세밀한 제어를 위해 MCP-Server-MySQL은 이제 스키마별 권한을 지원합니다. 이를 통해 각 데이터베이스에 서로 다른 액세스 수준(읽기 전용, 읽기-쓰기 등)을 부여할 수 있습니다.

구성 예제

SCHEMA_INSERT_PERMISSIONS=development:true,test:true,production:false
SCHEMA_UPDATE_PERMISSIONS=development:true,test:true,production:false
SCHEMA_DELETE_PERMISSIONS=development:false,test:true,production:false
SCHEMA_DDL_PERMISSIONS=development:false,test:true,production:false

자세한 내용과 보안 권장 사항은 README-MULTI-DB.md를 참조하세요.

테스트

데이터베이스 설정

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

테스트 데이터베이스 및 사용자 생성
-- 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

문제 해결

일반적인 문제

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

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

내 node bin 경로는 어디에서 찾을 수 있나요 ? 다음 명령을 실행하여 가져오세요.

PATH 의 경우

echo "$(which node)/../"    

NODE_PATH 의 경우

echo "$(which node)/../../lib/node_modules"    

Claude Desktop 특정 문제
- Claude Desktop에서 "서버 연결 끊김" 로그가 표시되면 ~/Library/Logs/Claude/mcp-server-mcp_server_mysql.log 에서 로그를 확인하세요.
- Node 바이너리와 서버 스크립트 모두에 절대 경로를 사용하고 있는지 확인하세요.
- .env 파일이 제대로 로드되는지 확인하세요. 구성에서 명시적 환경 변수를 사용하세요.
- 연결 문제가 있는지 확인하려면 명령줄에서 직접 서버를 실행해보세요.
- 쓰기 작업(INSERT, UPDATE, DELETE)이 필요한 경우 구성에서 해당 플래그를 "true"로 설정합니다.
  "env": { "ALLOW_INSERT_OPERATION": "true", // Enable INSERT operations "ALLOW_UPDATE_OPERATION": "true", // Enable UPDATE operations "ALLOW_DELETE_OPERATION": "true" // Enable DELETE operations }
- MySQL 사용자에게 활성화하려는 작업에 대한 적절한 권한이 있는지 확인하세요.
- 직접 실행 구성의 경우 다음을 사용하세요.
  { "mcpServers": { "mcp_server_mysql": { "command": "/full/path/to/node", "args": [ "/full/path/to/mcp-server-mysql/dist/index.js" ], "env": { "MYSQL_HOST": "127.0.0.1", "MYSQL_PORT": "3306", "MYSQL_USER": "root", "MYSQL_PASS": "your_password", "MYSQL_DB": "your_database" } } } }
인증 문제
- MySQL 8.0 이상의 경우 서버가 caching_sha2_password 인증 플러그인을 지원하는지 확인하세요.
- MySQL 사용자가 올바른 인증 방법으로 구성되었는지 확인하세요.
- 필요한 경우 레거시 인증을 사용하여 사용자를 생성해보세요.
  CREATE USER 'user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';
  @리주앙스
Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'dotenv' imported from . 다음 해결 방법을 시도해 보세요.

npx -y -p @benborla29/mcp-server-mysql -p dotenv mcp-server-mysql

@lizhuangs에게 감사드립니다

기여하다

기여를 환영합니다! 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 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 라이선스 파일을 참조하세요.

Integrations