mysql-mcp-server

MCP 클라이언트(Claude Desktop, Claude Code 등)가 select, insert, update, delete 네 가지 도구를 통해 MySQL 데이터베이스에 SQL을 실행할 수 있게 해주는 Model Context Protocol (MCP) 서버입니다.

이 서버는 uv로 관리되는 Python 패키지로 실행되며, 클라이언트가 시작한 하위 프로세스로서 stdio를 통해 클라이언트와 통신합니다.

요구 사항

• Python 3.11+

• uv

• 연결 가능한 MySQL 서버

Related MCP server: Universal Database MCP Server

설치

uv sync

구성

서버는 여섯 가지 값을 필요로 하며, 각 값은 환경 변수 및/또는 CLI 플래그로 설정할 수 있습니다(CLI 플래그가 환경 변수보다 우선합니다):

필수 값이 누락되었거나 MYSQL_MODE가 readonly/readwrite가 아니면 서버는 stderr에 오류를 출력하고 시작하지 않은 채 종료 코드 1로 종료됩니다.

• readonly 모드: select 도구만 허용됩니다. insert/update/delete는 PERMISSION_DENIED 오류와 함께 거부됩니다.

• readwrite 모드: 네 가지 도구가 모두 허용됩니다.

모드는 프로세스 수명 동안 고정되며 런타임에 변경할 수 없습니다.

보안 권장사항: readonly 모드는 애플리케이션 수준의 보호 장치일 뿐 데이터베이스 권한을 대체하지 않습니다. 가능하면 readonly 모드가 SELECT 권한만 있는 MySQL 계정을 가리키도록 하세요.

.env 파일이 필요한가요? 아닙니다. 서버 자체는 .env 파일을 읽지 않습니다. CLI 플래그와 실제 프로세스 환경 변수(os.environ)만 읽습니다. 해당 환경에 값을 넣는 방법은 실행 방식에 따라 다릅니다:

• MCP 서버로 실행하는 경우 (아래 MCP 클라이언트에서 연결하기 참조): 클라이언트(Claude Desktop/Code)가 서버 프로세스를 생성하고 자체 JSON 구성의 env 블록을 환경 변수로 직접 주입합니다. .env 파일은 관여하지 않으며 필요하지 않습니다.

• 로컬 개발/테스트를 위해 CLI를 직접 실행하는 경우: .env는 여섯 개의 변수를 일일이 export하지 않아도 되도록 해주는 편의 기능일 뿐입니다. .env.example을 .env로 복사하고 실제 값을 입력한 뒤 명시적으로 로드하세요. 자동으로 읽히지 않습니다:

  uv run --env-file .env mysql-mcp-server

  .env는 git-ignored 처리되어 있으며 절대 커밋하면 안 됩니다.

실행

# Environment variables (or use `uv run --env-file .env mysql-mcp-server`, see above)
export MYSQL_MODE=readonly
export MYSQL_HOST=127.0.0.1
export MYSQL_PORT=3306
export MYSQL_USER=app_user
export MYSQL_PASSWORD=secret
export MYSQL_DATABASE=mydb
uv run mysql-mcp-server

# Or, equivalently, via CLI flags
uv run mysql-mcp-server \
  --mysql-mode readonly \
  --mysql-host 127.0.0.1 \
  --mysql-port 3306 \
  --mysql-user app_user \
  --mysql-password secret \
  --mysql-database mydb

MCP 클라이언트에서 연결하기

Claude Desktop / Claude Code

MCP 클라이언트의 서버 구성에 항목을 추가하세요(예: Claude Desktop의 claude_desktop_config.json 또는 Claude Code의 .mcp.json):

{
  "mcpServers": {
    "mysql": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mysql-mcp-server",
        "run",
        "mysql-mcp-server"
      ],
      "env": {
        "MYSQL_MODE": "readonly",
        "MYSQL_HOST": "127.0.0.1",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "app_user",
        "MYSQL_PASSWORD": "secret",
        "MYSQL_DATABASE": "mydb"
      }
    }
  }
}

구성을 편집한 후 클라이언트를 다시 시작하세요. 그러면 select, insert, update, delete 도구(MYSQL_MODE에 따라 다름)를 모델이 사용할 수 있습니다.

도구

네 가지 도구 모두 {"query": string, "params"?: array} 형식을 받으며 query에서 항상 %s 매개변수 바인딩 플레이스홀더를 사용합니다. 사용자 입력을 쿼리에 문자열 포맷으로 넣지 마세요.

모든 도구 호출은 다음 중 하나를 반환합니다:

{ "success": true, "data": { ... } }

{ "success": false, "error": { "code": "...", "message": "..." } }

오류 코드: PERMISSION_DENIED, INVALID_QUERY_TYPE, MULTI_STATEMENT_NOT_ALLOWED, DB_CONNECTION_ERROR, DB_EXECUTION_ERROR, INTERNAL_ERROR.

멀티 스테이트먼트 쿼리(;로 구분)와 모든 DDL/권한 문(DROP, TRUNCATE, ALTER, GRANT, CREATE USER, ...)은 항상 거부됩니다. 위의 네 가지 허용된 문 유형만 수락되기 때문입니다.

개발

uv sync
uv run ruff format .
uv run ruff check .
uv run pytest -v
uv run uv build   # packaging check

문제 해결

• 서버가 종료 코드 1로 즉시 종료됨: 필수 MYSQL_* 값이 누락되었거나 MYSQL_MODE가 잘못된 경우입니다. 어떤 값인지 stderr를 확인하세요.

• DB_CONNECTION_ERROR: MySQL에 연결할 수 없거나 자격 증명이 잘못된 경우입니다. 서버는 계속 실행되며 다음 도구 호출 시 연결을 재시도합니다.

• insert/update/delete에서 PERMISSION_DENIED: 서버가 readonly 모드로 실행 중입니다. 쓰기가 의도된 경우 MYSQL_MODE=readwrite로 다시 시작하세요.

버전 이력

• 0.1.0 — 최초 릴리스: select/insert/update/delete 도구, readonly/readwrite 모드 정책, stdio MCP 전송, 연결 끊김 시 자동 재연결 및 재시도.