MySQL 쿼리 MCP 서버

AI 비서에 읽기 전용 MySQL 데이터베이스 쿼리를 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. AI 기반 도구에서 직접 쿼리를 실행하고, 데이터베이스 구조를 탐색하고, 데이터를 분석할 수 있습니다.

지원되는 AI 도구

이 MCP 서버는 다음을 포함하여 모델 컨텍스트 프로토콜을 지원하는 모든 도구와 함께 작동합니다.

커서 IDE : .cursor/mcp.json 에 설정
Anthropic Claude : 호환되는 MCP 클라이언트와 함께 사용
기타 MCP 호환 AI 어시스턴트 : 도구의 MCP 구성 지침을 따르세요.

기능 및 제한 사항

그것이 하는 일

✅ 읽기 전용 MySQL 쿼리(SELECT, SHOW, DESCRIBE만 해당) 실행
✅ 미리 정의된 환경(로컬, 개발, 스테이징, 프로덕션)에서 작업
✅ 데이터베이스 정보 및 메타데이터 제공
✅ 사용 가능한 데이터베이스 환경 나열
✅ 안전한 데이터베이스 접근을 위한 SSL 연결 지원
✅ 장시간 실행되는 작업을 방지하기 위해 쿼리 시간 초과를 구현합니다.

그것이 하지 않는 것

❌ 쓰기 작업(INSERT, UPDATE, DELETE, CREATE, ALTER 등)을 실행합니다.
❌ 사용자 정의 환경 이름 지원(로컬, 개발, 스테이징, 프로덕션으로 제한)
❌ 데이터베이스 설계 또는 스키마 생성 기능 제공
❌ 전체 데이터베이스 관리 도구로서의 기능

이 도구는 읽기 전용 쿼리를 통한 데이터 조사 및 탐색을 위해 특별히 설계되었습니다. 데이터베이스 관리, 스키마 관리 또는 데이터 수정에는 사용할 수 없습니다.

빠른 설치

지엑스피1

설치 지침

MCP 서버를 사용하도록 AI 도구 구성

MCP 구성 파일을 만들거나 편집합니다(예: Cursor IDE의 경우 .cursor/mcp.json ):

기본 구성:

{
  "mysql": {
    "name": "MySQL Query MCP",
    "description": "MySQL read-only query access through MCP",
    "type": "bin", 
    "enabled": true,
    "bin": "mysql-query-mcp"
  }
}

데이터베이스 자격 증명을 통한 포괄적인 구성:

{
  "mysql": {
    "command": "npx",
    "args": ["mysql-query-mcp-server@latest"],
    "env": {
      "LOCAL_DB_HOST": "localhost",
      "LOCAL_DB_USER": "root",
      "LOCAL_DB_PASS": "<YOUR_LOCAL_DB_PASSWORD>",
      "LOCAL_DB_NAME": "your_database",
      "LOCAL_DB_PORT": "3306",
      
      "DEVELOPMENT_DB_HOST": "dev.example.com",
      "DEVELOPMENT_DB_USER": "<DEV_USER>",
      "DEVELOPMENT_DB_PASS": "<DEV_PASSWORD>",
      "DEVELOPMENT_DB_NAME": "your_database",
      "DEVELOPMENT_DB_PORT": "3306",
      
      "STAGING_DB_HOST": "staging.example.com",
      "STAGING_DB_USER": "<STAGING_USER>",
      "STAGING_DB_PASS": "<STAGING_PASSWORD>",
      "STAGING_DB_NAME": "your_database",
      "STAGING_DB_PORT": "3306",
      
      "PRODUCTION_DB_HOST": "prod.example.com",
      "PRODUCTION_DB_USER": "<PRODUCTION_USER>",
      "PRODUCTION_DB_PASS": "<PRODUCTION_PASSWORD>",
      "PRODUCTION_DB_NAME": "your_database",
      "PRODUCTION_DB_PORT": "3306",
      
      "DEBUG": "false",
      "MCP_MYSQL_SSL": "true",
      "MCP_MYSQL_REJECT_UNAUTHORIZED": "false"
    }
  }
}

올바른 구성 접근 방식 선택

MySQL MCP 서버를 구성하는 방법에는 두 가지가 있습니다.

바이너리 구성 ( type: "bin" , bin: "mysql-query-mcp" )
- 사용 시기 : 패키지를 전역으로 설치한 경우( npm install -g mysql-query-mcp-server )
- 장점 : 구성이 더 간단함
- 단점 : 글로벌 설치가 필요합니다
명령 구성 ( command: "npx" , args: ["mysql-query-mcp-server@latest"] )
- 사용 시기 : 글로벌하게 설치하지 않고 최신 버전을 사용하고 싶을 때
- 장점 : 글로벌 설치가 필요 없고 모든 구성이 하나의 파일에 들어 있습니다.
- 단점 : 구성이 더 복잡함

워크플로에 가장 적합한 방식을 선택하세요. 두 방법 모두 MCP를 지원하는 모든 AI 비서에서 정상적으로 작동합니다.

중요 구성 참고 사항

전체 환경 이름을 사용해야 합니다: LOCAL_, DEVELOPMENT_, STAGING_, PRODUCTION_
DEV_ 또는 PROD_와 같은 약어는 작동하지 않습니다.
DEBUG, MCP_MYSQL_SSL과 같은 글로벌 설정은 모든 환경에 적용됩니다.
최소한 하나의 환경(일반적으로 "로컬")을 구성해야 합니다.
사용하려는 환경만 구성하면 됩니다.
보안상의 이유로 프로덕션 자격 증명에 대해 환경 변수 또는 보안 자격 증명 저장소를 사용하는 것을 고려하십시오.

구성 옵션

환경 변수	설명	기본
디버그	디버그 로깅 활성화	거짓
[ENV]_DB_호스트	환경을 위한 데이터베이스 호스트	-
[ENV]_DB_사용자	데이터베이스 사용자 이름	-
[ENV]_DB_패스	데이터베이스 비밀번호	-
[ENV]_DB_이름	데이터베이스 이름	-
[ENV]_DB_포트	데이터베이스 포트	3306
[ENV]_DB_SSL	SSL 연결 활성화	거짓
MCP_MYSQL_SSL	모든 연결에 SSL을 활성화하세요	거짓
MCP_MYSQL_거부_무단	SSL 인증서 확인	진실

AI 어시스턴트와의 통합

AI 비서는 MCP 서버를 통해 MySQL 데이터베이스와 상호 작용할 수 있습니다. 다음은 몇 가지 예입니다.

예시 쿼리:

Can you use the query tool to show me the first 10 users from the database? Use the local environment.

I need to analyze our sales data. Can you run a SQL query to get the total sales per region for last month from the development database?

Can you use the info tool to check what tables are available in the staging database?

Can you list all the available database environments we have configured?

MySQL MCP 도구 사용

MySQL Query MCP 서버는 AI 어시스턴트가 사용할 수 있는 세 가지 주요 도구를 제공합니다.

1. 질의

특정 환경에 대해 읽기 전용 SQL 쿼리를 실행합니다.

Use the query tool to run:
SELECT * FROM customers WHERE signup_date > '2023-01-01' LIMIT 10;
on the development environment

2. 정보

귀하의 데이터베이스에 대한 자세한 정보를 얻으세요:

Use the info tool to check the status of our production database.

3. 환경

구성에서 구성된 모든 환경을 나열합니다.

Use the environments tool to show me which database environments are available.

사용 가능한 도구

MySQL Query MCP 서버는 세 가지 주요 도구를 제공합니다.

1. 질의

읽기 전용 SQL 쿼리를 실행합니다.

-- Example query to run with the query tool
SELECT * FROM users LIMIT 10;

지원되는 쿼리 유형(엄격히 제한됨) :

SELECT 문
SHOW 명령
DESCRIBE/DESC 테이블

2. 정보

귀하의 데이터베이스에 대한 자세한 정보를 얻으세요:

서버 버전
연결 상태
데이터베이스 변수
프로세스 목록
사용 가능한 데이터베이스

3. 환경

구성에서 구성된 모든 환경을 나열합니다.

Use the environments tool to show me which database environments are available.

보안 고려 사항

✅ 읽기 전용 쿼리만 허용됩니다(SELECT, SHOW, DESCRIBE)
✅ 각 환경에는 자체적으로 격리된 연결 풀이 있습니다.
✅ SSL 연결은 프로덕션 환경에서 지원됩니다.
✅ 쿼리 시간 초과로 인해 폭주 작업이 방지됩니다.
⚠️ 데이터베이스 자격 증명에 대해 보안 자격 증명 관리 사용을 고려하세요

문제 해결

연결 문제

연결에 문제가 있는 경우:

MCP 구성에서 데이터베이스 자격 증명을 확인하세요.
MySQL 서버가 실행 중이고 접근 가능한지 확인하세요.
연결을 차단하는 방화벽 규칙을 확인하세요
구성에서 DEBUG=true를 설정하여 디버그 모드를 활성화합니다.

일반적인 오류

오류: 환경에 사용 가능한 연결 풀이 없습니다.

해당 환경에 필요한 모든 환경 변수를 정의했는지 확인하세요.
지원되는 환경 이름(로컬, 개발, 스테이징, 프로덕션) 중 하나를 사용하고 있는지 확인하세요.

오류: 쿼리 실행에 실패했습니다.

SQL 구문을 확인하세요
지원되는 쿼리 유형(SELECT, SHOW, DESCRIBE)만 사용하고 있는지 확인하세요.
귀하의 쿼리가 실제로 읽기 전용인지 확인하세요.

더욱 포괄적인 문제 해결 방법은 문제 해결 가이드를 참조하세요.

AI 어시스턴트와 통합하는 방법에 대한 예는 통합 예를 참조하세요.

MCP 프로토콜에 대한 구현 세부 사항은 MCP README를 참조하세요.

기여하다

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.

CI/CD 및 릴리스 프로세스

이 프로젝트에서는 지속적인 통합과 자동화된 릴리스를 위해 GitHub Actions를 사용합니다.

CI/CD 워크플로

CI/CD 파이프라인은 다음으로 구성됩니다.

빌드 및 테스트 : main 및 develop 브랜치에 대한 모든 푸시와 이러한 브랜치에 대한 풀 리퀘스트에서 실행됩니다.
- Node.js 16.x 및 18.x로 코드베이스를 테스트합니다.
- 패키지가 올바르게 빌드되는지 확인합니다.
- 모든 테스트가 통과되었는지 확인합니다.
릴리스 : 변경 사항이 main 브랜치에 푸시되고 빌드/테스트 작업이 성공하면 실행됩니다.
- release-please 사용하여 버전 범프 및 변경 로그 업데이트를 관리합니다.
- 기존 커밋을 기반으로 버전 변경 사항을 포함하는 릴리스 PR을 생성합니다.
- 릴리스 PR이 병합되면 자동으로 npm에 게시됩니다.

릴리스 프로세스

이 프로젝트는 의미적 버전 관리를 따릅니다.

주요 버전 : 주요 변경 사항(이전 버전과 호환되지 않음)
마이너 버전 : 새로운 기능(이전 버전과 호환 가능)
패치 버전 : 버그 수정 및 사소한 개선 사항

커밋은 기존 커밋 형식을 따라야 합니다.

feat: add new feature - 마이너 버전 범프
fix: resolve bug - 패치 버전 범프
docs: update documentation - 버전 범프 없음
chore: update dependencies - 버전 범프 없음
BREAKING CHANGE: change API - 주요 버전 범프

main 에 푸시하면 release-please 커밋을 분석하고 적절한 버전 범프 및 변경 로그 항목으로 릴리스 PR을 자동으로 생성하거나 업데이트합니다.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

작가

Abou Koné - 엔지니어링 리더 겸 CTO

자세한 정보나 지원이 필요하면 GitHub 저장소에서 이슈를 열어 주세요.

MySQL Query MCP Server

Integrations