MySQL MCP Server

MySQL 데이터베이스와의 안전한 상호작용을 지원하는 Model Context Protocol(MCP) 구현체입니다. 이 서버 구성 요소는 AI 애플리케이션(호스트/클라이언트)과 MySQL 데이터베이스 간의 통신을 구축하며, 제어된 인터페이스를 통해 데이터베이스 탐색과 분석을 더 안전하고 구조화된 방식으로 수행합니다.

참고: MySQL MCP Server는 STDIO(표준 입출력)와 Streamable HTTP(SSE) 두 가지 전송 모드를 모두 지원합니다. 원격/자체 호스팅 배포에는 SSE 모드를 권장합니다.

배포 방식

• 관리형 — Fronteir AI가 서버를 대신 실행하므로 로컬 설정이 필요 없습니다.

• 로컬 — Smithery가 사용자 컴퓨터에 서버를 설치하고 실행합니다.

Related MCP server: MCP MySQL Server

기능

• 리소스 형태로 사용 가능한 MySQL 테이블 나열

• 테이블 내용 읽기

• 완벽한 오류 처리를 갖춘 SQL 쿼리 실행

• 다중 데이터베이스 모드(선택적 MYSQL_DATABASE)

• SSE/HTTP 전송 지원(MCP_TRANSPORT=sse)

• SSH 터널 지원

• 전체 테이블 구조 정보

• 테이블 데이터 샘플링

• 환경 변수를 통한 안전한 데이터베이스 접근

• 완벽한 로깅

설치

수동 설치

pip install mysql-mcp-server

Smithery를 통한 설치

Smithery를 사용하여 Claude Desktop용 MySQL MCP Server를 자동으로 설치합니다:

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

Claude Code CLI를 통한 설치

claude mcp add --transport stdio designcomputer-mysql_mcp_server uvx mysql_mcp_server

Autohand Code CLI를 통한 설치

autohand mcp add mysql env MYSQL_HOST=localhost MYSQL_PORT=3306 MYSQL_USER=your_username MYSQL_PASSWORD=your_password MYSQL_DATABASE=your_database uvx mysql_mcp_server

mcp add 뒤에 --scope project를 추가하면 등록 정보가 현재 작업 공간에 유지됩니다. 현재 CLI에 대한 자세한 내용은 Autohand Code를 참조하세요.

구성

다음 환경 변수를 설정합니다:

MYSQL_HOST=localhost     # 数据库主机
MYSQL_PORT=3306         # 可选：数据库端口（不指定时默认 3306）
MYSQL_USER=your_username
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=your_database # 可选：留空则进入多数据库模式

# 高级配置
MYSQL_SSL_MODE=DISABLED  # DISABLED、REQUIRED、VERIFY_CA、VERIFY_IDENTITY
MYSQL_CONNECT_TIMEOUT=10 # 超时时间（秒）

# 连接行为（可选）
MYSQL_SQL_MODE=TRADITIONAL           # 连接所应用的 SQL mode（默认：TRADITIONAL）

# 兼容性（可选）
MYSQL_CHARSET=utf8mb4
MYSQL_COLLATION=utf8mb4_unicode_ci
MYSQL_AUTH_PLUGIN=       # 例如旧版 MySQL 使用 mysql_native_password
MYSQL_USE_PURE=false     # 强制使用纯 Python 连接器（默认：false）
MYSQL_RAISE_ON_WARNINGS=false        # 出现 SQL 警告时抛出异常（默认：false）

# SSE 传输（可选）
MCP_TRANSPORT=stdio      # stdio 或 sse
MCP_SSE_HOST=0.0.0.0     # 监听所有网卡（Docker/托管部署需要）
PORT=8000                # HTTP 端口（MCP_SSE_PORT 的回退值）
MCP_SSE_ALLOWED_HOSTS=   # 逗号分隔的允许 Host 头（默认：localhost:{port},127.0.0.1:{port}）

# SSH 隧道（可选）
MYSQL_SSH_ENABLE=false   # 设为 true 启用
MYSQL_SSH_HOST=          # SSH 跳板机
MYSQL_SSH_PORT=22        # SSH 端口
MYSQL_SSH_USER=          # SSH 用户名
MYSQL_SSH_KEY_PATH=      # SSH 私钥路径
MYSQL_SSH_REMOTE_HOST=localhost # 从跳板机视角看的目标主机
MYSQL_SSH_REMOTE_PORT=3306
MYSQL_LOCAL_PORT=3330

.env 파일 로드

서버 시작 시 python-dotenv를 통해 .env 파일이 자동으로 로드되므로, 로컬 사용은 다음과 같이 하면 됩니다:

cp .env.example .env   # 然后填入你的凭据

이 파일은 프로세스 작업 디렉터리(및 상위 디렉터리)에서 읽히므로, 프로젝트 디렉터리에서 서버를 직접 시작하면 정상적으로 작동합니다.

⚠️ Claude Code / Claude Desktop: 이러한 호스트는 자체 작업 디렉터리에서 서버를 시작하므로 프로젝트의 .env를 찾을 수 없으며, Missing required database configuration 오류가 표시됩니다. MYSQL_* 값을 MCP 구성의 env 블록(아래 "사용 방법" 참조)에 직접 넣고 .env에 의존하지 마세요.

다중 데이터베이스 모드

MYSQL_DATABASE가 설정되지 않은 경우 서버는 다중 데이터베이스 모드로 진입합니다:

• list_resources는 모든 사용자 데이터베이스를 반환합니다(시스템 데이터베이스는 필터링됨).

• SQL 쿼리에서 mydb.mytable과 같은 정규화된 테이블 이름을 사용합니다.

• 참고: 단일 SQL 문만 지원하며, 다중 문 쿼리(예: USE db; SELECT ...)는 지원하지 않습니다.

관리 페이지 및 다중 데이터베이스 별칭(SSE 모드)

SSE 모드로 서버를 시작하고 내장 관리 페이지를 열면 여러 데이터베이스 연결을 관리할 수 있으며, 각 연결에 별도의 읽기/쓰기 계정을 구성할 수 있습니다:

# Windows PowerShell
$env:MCP_TRANSPORT="sse"; $env:MCP_SSE_PORT="8000"; python -m mysql_mcp_server
# Linux/macOS
MCP_TRANSPORT=sse MCP_SSE_PORT=8000 python -m mysql_mcp_server

관리 페이지: http://127.0.0.1:8000/admin/(루프백 전용 — 관리 API와 페이지는 비루프백 클라이언트와 알 수 없는 Host 헤더를 거부합니다. 리버스 프록시 뒤에 두지 마세요).

각 별칭은 다음을 구성할 수 있습니다:

클라이언트는 별칭으로 연결합니다: http://127.0.0.1:8000/sse?alias=db1 (alias를 생략하면 기본 별칭 사용). config/databases.json에 항목이 없으면 기존 MYSQL_* 환경 변수가 이전 버전과의 호환성을 위한 단일 데이터베이스 폴백으로 계속 작동합니다(이 모드에서는 읽기/쓰기가 동일한 계정을 공유).

위의 다중 데이터베이스 모드와의 차이점에 유의하세요: 그 모드는 단일 연결에서 여러 스키마를 노출하는 반면, 별칭 관리는 여러 연결을 관리하며 각 연결에 독립적인 계정과 쓰기 정책이 있습니다.

쓰기 작업 확인 방법: 서버는 각 문장에 대해 3단계 판정(읽기/쓰기/삭제)을 수행합니다. 읽기 작업은 쿼리 계정으로 직접 실행하고, 쓰기 작업과 삭제 작업은 MCP elicitation 팝업을 통해 전체 SQL을 표시합니다 — 수락하면 작업 계정으로 실행하고, 거부하면 중단합니다. 클라이언트가 elicitation을 지원하지 않는 경우 별칭의 write_policy에 따라 폴백 동작이 결정됩니다(위 표 참조). 모든 쓰기 작업 시도는 관리 페이지의 감사 목록에 기록됩니다(디스크에는 logs/audit.log).

사용 가능한 도구

execute_sql

임의의 표준 SQL 쿼리를 실행합니다.

• 매개변수: query(문자열)

• 기능: SELECT, SHOW, DESCRIBE 및 DML(INSERT, UPDATE, DELETE)을 지원합니다. DML 작업에는 파괴적 작업 경고 표시가 있습니다.

• 제한: 단일 문만 지원하며, 다중 문 쿼리는 지원하지 않습니다.

• 크로스 데이터베이스: MYSQL_DATABASE 설정과 관계없이 database.table 표기법으로 모든 데이터베이스를 쿼리할 수 있습니다.

get_schema_info

데이터베이스 구조에 대한 상세 메타데이터를 제공합니다.

• 매개변수: table_name(선택적 문자열)

• 출력: 열 이름, 유형, null 허용 여부, 기본값 및 주석.

• 크로스 데이터베이스: database.table을 전달하면 MYSQL_DATABASE 외부의 데이터베이스를 쿼리할 수 있습니다. 테이블 이름만 전달하면 구성된 데이터베이스를 사용합니다.

• 식별자 규칙: 이름은 영숫자, 밑줄 및 $만 포함할 수 있습니다(점 하나는 database.table 구분자로 허용).

get_table_sample

대표적인 데이터 샘플을 가져옵니다.

• 매개변수: table_name(문자열), limit(선택적 정수, 최대 20)

• 용도: 큰 결과 집합을 가져오지 않고도 데이터 형식과 내용을 빠르게 파악할 수 있습니다.

• 크로스 데이터베이스: database.table을 전달하면 MYSQL_DATABASE 외부의 데이터베이스에서 샘플링할 수 있습니다. 테이블 이름만 전달하면 구성된 데이터베이스를 사용합니다.

• 식별자 규칙: 이름은 영숫자, 밑줄 및 $만 포함할 수 있습니다(점 하나는 database.table 구분자로 허용).

사용 가능한 프롬프트(Prompts)

도구 외에도 서버는 MCP 프롬프트를 제공합니다 — 클라이언트가 필요에 따라 시작할 수 있는 안내형 다단계 워크플로우입니다. Claude Code에서는 슬래시 명령(/mcp__<server>__<prompt>)으로 나타나고, Claude Desktop에서는 프롬프트(+) 메뉴에 있습니다.

예시(Claude Code):

/mcp__mysql__explore_database
/mcp__mysql__analyze_table customers

두 프롬프트 모두 기존 get_schema_info 및 get_table_sample 도구를 오케스트레이션합니다. explore_database는 또한 리소스 목록을 사용하여 테이블을 열거합니다.

사용 방법

Claude Desktop과 함께 사용

claude_desktop_config.json에 다음 내용을 추가합니다:

{
  "mcpServers": {
    "mysql": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mysql_mcp_server",
        "run",
        "mysql_mcp_server"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

더 자세한 예시와 각 에이전트별 안내는 MCP_USECASES.md를 참조하세요.

Visual Studio Code와 함께 사용

mcp.json에 다음 내용을 추가합니다:

{
  "mcpServers": {
    "mysql": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "mysql-mcp-server",
        "mysql_mcp_server"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_username",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

참고: uv를 먼저 설치해야 합니다.

MCP Inspector로 디버깅

MySQL MCP Server는 독립 실행형 또는 Python 명령줄로 직접 시작하도록 설계된 프로그램이 아니지만, MCP Inspector를 사용하여 디버깅할 수 있습니다.

MCP Inspector는 MCP 구현을 테스트하고 디버깅하는 편리한 방법을 제공합니다:

# 安装依赖
pip install -r requirements.txt
# 使用 MCP Inspector 调试（不要直接用 Python 运行）

MySQL MCP Server는 Claude Desktop과 같은 AI 애플리케이션에 통합되도록 설계되었으며, 독립 실행형 Python 프로그램으로 직접 실행해서는 안 됩니다.

개발

# 克隆仓库
git clone https://github.com/designcomputer/mysql_mcp_server.git
cd mysql_mcp_server
# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows 上用 `venv\Scripts\activate`
# 安装开发依赖
pip install -r requirements-dev.txt
# 复制示例配置并填入你的凭据
cp .env.example .env
# 编辑 .env，填入 MySQL 连接信息
# 运行测试
pytest

보안 주의사항

• 식별자 검증: get_schema_info 및 get_table_sample에 전달되는 테이블 이름과 데이터베이스 이름은 엄격한 화이트리스트 검증을 거칩니다(영숫자, 밑줄 및 $만 허용, 점 하나는 database.table 구분자로 허용). SQL 주입을 방지하기 위해 다른 특수 문자는 모두 거부됩니다.

• 암호화 접근: 원격 연결 보안을 위해 SSL/TLS 및 SSH 터널을 완전히 지원합니다.

• 로그 개인정보 보호: 비밀번호와 SSH 개인 키는 서버 로그에서 자동으로 마스킹됩니다.

• 최소 권한: 항상 최소 권한의 전용 MySQL 사용자를 사용하세요.

• SSE 전송에는 내장 인증이 없습니다. SSE 서버는 기본적으로 0.0.0.0에 바인딩되고 자격 증명 없이 연결을 수락합니다. localhost 외부에 노출하는 경우 강제 인증이 있는 리버스 프록시(nginx, Caddy, Traefik) 뒤에 두세요. nginx + HTTP Basic Auth 예시:

  location /sse {
      auth_basic "MCP";
      auth_basic_user_file /etc/nginx/.htpasswd;
      proxy_pass http://127.0.0.1:8000;
      proxy_set_header Host $host;
      proxy_buffering off;
  }
  location /messages/ {
      auth_basic "MCP";
      auth_basic_user_file /etc/nginx/.htpasswd;
      proxy_pass http://127.0.0.1:8000;
      proxy_set_header Host $host;
  }

  MCP_SSE_HOST=127.0.0.1을 설정하면 서버가 루프백 주소만 수신하므로 프록시가 유일한 공개 진입점이 됩니다. MCP_SSE_ALLOWED_HOSTS를 프록시가 전달하는 공개 호스트 이름으로 설정하세요(예: MCP_SSE_ALLOWED_HOSTS=myserver.example.com:443).

배포 보안 전체 가이드는 SECURITY.md를 참조하세요.

보안 모범 사례

이 MCP 구현은 작동을 위해 데이터베이스 접근 권한이 필요합니다. 보안을 위해:

1. 전용 MySQL 사용자를 생성하고 최소 권한을 부여하세요.

2. 절대 root 자격 증명이나 관리자 계정을 사용하지 마세요.

3. 데이터베이스 접근을 필요한 작업으로 제한하세요.

4. 감사를 위해 로깅을 활성화하세요.

5. 데이터베이스 접근에 대한 정기적인 보안 검토를 수행하세요.

자세한 운영 지침은 MySQL 보안 구성 가이드를 참조하세요. 다음을 포함합니다:

• 제한된 MySQL 사용자 생성

• 적절한 권한 설정

• 데이터베이스 접근 모니터링

• 보안 모범 사례

⚠️ 중요: 데이터베이스 접근을 구성할 때 반드시 최소 권한 원칙을 따르세요.

라이선스

MIT License - 자세한 내용은 LICENSE 파일을 참조하세요.

기여하기

1. 이 저장소를 Fork하세요.

2. 기능 브랜치를 생성하세요(git checkout -b feature/amazing-feature).

3. 변경 사항을 커밋하세요(git commit -m 'Add some amazing feature').

4. 브랜치를 푸시하세요(git push origin feature/amazing-feature).

5. Pull Request를 생성하세요.