MySQL MCP 서버

영어 | 중국어

개요

MySQL을 통해 데이터베이스 상호작용 기능을 제공하는 모델 컨텍스트 프로토콜(MCP) 서버 구현입니다. 이 서버를 통해 SQL 쿼리 실행, 테이블 생성, 데이터베이스 스키마 정보 탐색이 가능합니다.

Related MCP server: MCP MySQL Server

구성 요소

도구

서버는 5가지 핵심 도구를 제공합니다.

쿼리 도구

• read_query

  • 데이터베이스에서 데이터를 읽기 위해 SELECT 쿼리를 실행합니다.

  • 입력:
    * query (문자열): 실행할 SELECT SQL 쿼리

  • 반환: 객체 배열로 쿼리 결과

• write_query

  • INSERT, UPDATE 또는 DELETE 쿼리 실행

  • 입력:
    * query (문자열): SQL 수정 쿼리

  • 반환: { affected_rows: number }

• create_table

  • 데이터베이스에 새 테이블을 만듭니다

  • 입력:
    * query (문자열): CREATE TABLE SQL 문

  • 반환: 테이블 생성 확인

스키마 도구

• list_tables

  • 데이터베이스의 모든 테이블 목록을 가져옵니다.

  • 입력이 필요하지 않습니다

  • 반환: 테이블 이름 배열

• describe_table

  • 특정 테이블에 대한 스키마 정보 보기

  • 입력:
    * table_name (문자열): 설명할 테이블의 이름

  • 반환: 이름과 유형이 포함된 열 정의 배열

설치

필수 조건

• 파이썬 3.10+

• MySQL 데이터베이스

• 필요한 Python 패키지:

  • mcp (모델 컨텍스트 프로토콜)

  • sqlalchemy

  • pymysql (또는 다른 MySQL 드라이버)

  • python-dotenv

  • uvicorn (HTTP 전송용)

Conda로 설정

먼저, conda 환경을 만들고 활성화합니다.

지엑스피1

그런 다음 필요한 종속성을 설치합니다.

# Method 1: Using pip
pip install "mcp[cli]>=0.1.0" "pymysql>=1.1.0" "sqlalchemy>=2.0.0" "python-dotenv>=1.0.0" "uvicorn>=0.27.0"

# Method 2: Using uv
uv pip install "mcp[cli]>=0.1.0" "pymysql>=1.1.0" "sqlalchemy>=2.0.0" "python-dotenv>=1.0.0" "uvicorn>=0.27.0"

구성

다음을 사용하여 서버를 구성할 수 있습니다.

환경 변수 파일(.env)

1. .env.template 파일을 복사하고 이름을 .env 로 바꿉니다.

cp .env.template .env

2. 구성에 맞게 .env 파일을 편집합니다.

# Database configuration
DB_URL=mysql+pymysql://username:password@localhost:3306/dbname

명령줄 인수

명령줄 인수를 사용하여 구성을 재정의할 수도 있습니다.

python src/mysql/server.py --db-url mysql+pymysql://username:password@localhost:3306/dbname

용법

서버 시작

# Using .env file configuration
python src/mysql/server.py

# Using command line arguments
python src/mysql/server.py --db-url mysql+pymysql://username:password@localhost:3306/dbname --transport http

MCP Inspector로 테스트

MCP Inspector 도구를 사용하여 서버를 테스트할 수 있습니다.

npx @modelcontextprotocol/inspector uv run /Users/caicongyang/IdeaProjects/tom/mcp-demo/src/mysql/server.py

이렇게 하면 서버가 시작되고 사용 가능한 도구를 대화형으로 테스트할 수 있습니다.

워크플로 예시

1. MySQL 데이터베이스 연결로 서버를 시작하세요

2. MCP 클라이언트를 사용하여 AI 모델을 서버에 연결합니다.

3. list_tables 도구를 사용하여 사용 가능한 테이블을 확인하세요.

4. 필요한 경우 create_table 로 테이블을 생성합니다.

5. write_query 로 데이터 삽입

6. read_query 로 데이터 쿼리하기

Claude Desktop과 함께 사용

자외선

claude_desktop_config.json 에 서버를 추가합니다.

"mcpServers": {
  "mysql": {
    "command": "uv",
    "args": [
      "--directory",
      "path_to_mcp_demo",
      "run",
      "python",
      "src/mysql/server.py",
      "--db-url",
      "mysql+pymysql://username:password@localhost/dbname"
    ]
  }
}

도커

claude_desktop_config.json 에 서버를 추가합니다.

"mcpServers": {
  "mysql": {
    "command": "docker",
    "args": [
      "run",
      "--rm",
      "-i",
      "-v",
      "mcp-mysql:/mcp",
      "mcp/mysql",
      "--db-url",
      "mysql+pymysql://username:password@localhost/dbname"
    ]
  }
}

패키지 설치

pip를 사용하여 패키지를 설치할 수도 있습니다.

# Install in development mode
pip install -e .

# Run using the installed package
mcp-mysql --db-url mysql+pymysql://username:password@localhost/dbname

커서 IDE에서

Cursor 는 AI 지원 IDE입니다. 이 MCP 서버를 Cursor와 통합하면 코딩 중에 MySQL 데이터베이스를 직접 쿼리할 수 있습니다.

커서 설정

1. MCP 서버를 시작합니다

   python src/mysql/server.py

2. 커서 설정에서 MCP 구성

   MCP 서버 URL을 추가하세요:

   http://localhost:8000

3. 커서 명령을 사용하여 MCP에 액세스하세요

   커서 편집기에서 다음을 사용하세요.

   /mcp mysql-query {"query": "SELECT * FROM users LIMIT 5"}

   매개변수화된 쿼리의 경우:

   /mcp mysql-query {"query": "SELECT * FROM users WHERE age > :min_age", "params": {"min_age": 30}}

API 참조

입력 형식

{
  "query": "SELECT * FROM users WHERE age > :min_age",
  "params": {
    "min_age": 30
  }
}

출력 형식

{
  "results": [
    {"id": 1, "name": "John", "age": 35},
    {"id": 2, "name": "Jane", "age": 42}
  ],
  "columns": ["id", "name", "age"],
  "rowcount": 2
}

보안 고려 사항

• 이 서버는 임의의 SQL 쿼리를 허용하므로 신뢰할 수 있는 환경에서 실행해야 합니다.

• 생산 단계에서는 적절한 액세스 제어 및 입력 검증을 구현합니다.

• 실행할 수 있는 SQL 명령 유형을 제한하는 것을 고려하세요.

• 중요 : 민감한 정보가 포함된 .env 파일을 버전 제어에 커밋하지 마십시오.

개발

프로젝트 구조

• src/mysql/server.py : 메인 서버 구현

• pyproject.toml : 패키지 구성

• README.md : 이 문서

새로운 기능 추가

새로운 기능으로 서버를 확장하려면:

1. @mcp.tool() 데코레이터를 사용하여 새 도구 추가

2. MySQLDatabase 클래스를 사용하여 도구 논리를 구현합니다.

3. 새로운 기능을 반영하도록 설명서를 업데이트하세요.

특허

이 MCP 서버는 MIT 라이선스에 따라 라이선스가 부여됩니다. 즉, MIT 라이선스의 약관에 따라 소프트웨어를 자유롭게 사용, 수정 및 배포할 수 있습니다.