MySQL MCP 서버

이 프로젝트는 Smithery의 Model Context Protocol (MCP)을 사용하여 MySQL 데이터베이스와 상호작용하는 서버입니다.

Installation

Installing via Smithery

To install MySQL Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @aqaranewbiz/mysql-aqaranewbiz --client claude

Manual Installation

npx @aqaranewbiz/mysql-aqaranewbiz

Configuration

The server requires the following environment variables to be set in your MCP settings configuration file:

{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "@aqaranewbiz/mysql-aqaranewbiz"],
      "env": {
        "MYSQL_HOST": "your_host",
        "MYSQL_USER": "your_user",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Available Tools

1. connect_db

Establish connection to MySQL database using provided credentials.

use_mcp_tool({
  server_name: "mysql",
  tool_name: "connect_db",
  arguments: {
    host: "localhost",
    user: "your_user",
    password: "your_password",
    database: "your_database"
  }
});

2. query

Execute SELECT queries with optional prepared statement parameters.

use_mcp_tool({
  server_name: "mysql",
  tool_name: "query",
  arguments: {
    sql: "SELECT * FROM users WHERE id = ?",
    params: [1]
  }
});

3. execute

Execute INSERT, UPDATE, or DELETE queries with optional prepared statement parameters.

use_mcp_tool({
  server_name: "mysql",
  tool_name: "execute",
  arguments: {
    sql: "INSERT INTO users (name, email) VALUES (?, ?)",
    params: ["John Doe", "john@example.com"]
  }
});

4. list_tables

List all tables in the connected database.

use_mcp_tool({
  server_name: "mysql",
  tool_name: "list_tables",
  arguments: {}
});

5. describe_table

Get the structure of a specific table.

use_mcp_tool({
  server_name: "mysql",
  tool_name: "describe_table",
  arguments: {
    table: "users"
  }
});

주요 기능

• MySQL 데이터베이스 연결 및 쿼리 실행
• MCP 프로토콜을 통한 표준화된 API 제공
• FastAPI 기반의 RESTful API 엔드포인트
• 환경 변수를 통한 설정 관리

시작하기

필수 요구사항

• Python 3.11 이상
• MySQL 서버
• Docker (선택사항)

환경 설정

1. .env 파일 생성:

MYSQL_HOST=your_mysql_host
MYSQL_USER=your_mysql_user
MYSQL_PASSWORD=your_mysql_password
MYSQL_DATABASE=your_database_name

설치 방법

로컬 설치 (권장)

1. Python 가상환경 생성 및 활성화:

# Windows
python -m venv venv
venv\Scripts\activate

# macOS/Linux
python3 -m venv venv
source venv/bin/activate

2. 의존성 설치:

pip install -r requirements.txt

3. 서버 실행:

python mcp_server.py

Docker 설치

1. Docker 이미지 빌드:

docker build -t mysql-mcp-server .

2. 컨테이너 실행:

docker run -e MYSQL_HOST=host -e MYSQL_USER=user -e MYSQL_PASSWORD=pass -e MYSQL_DATABASE=db mysql-mcp-server

로컬 개발 설정

1. 개발 환경 설정:

# 개발용 의존성 설치
pip install -r requirements-dev.txt  # 필요한 경우 생성

# 코드 포맷팅 및 린팅 설정
pip install black flake8

2. 코드 실행:

# 개발 모드로 실행
python mcp_server.py --dev

3. 테스트 실행:

# 테스트 실행
python -m pytest tests/

API 엔드포인트

서버 정보 조회

GET /status

서버의 상태와 사용 가능한 도구 목록을 반환합니다.

쿼리 실행

POST /execute

MySQL 쿼리를 실행하고 결과를 반환합니다.

개발 가이드

프로젝트 구조

@MCP-Server-for-Smithery/
├── mcp_server.py      # 메인 서버 코드
├── requirements.txt   # Python 의존성
├── Dockerfile        # Docker 설정
├── .env              # 환경 변수 (템플릿)
└── tests/            # 테스트 코드

새로운 기능 추가

1. mcp_server.py에 새로운 도구 추가
2. 필요한 의존성 requirements.txt에 추가
3. 테스트 코드 작성
4. Docker 이미지 재빌드 (Docker 사용 시)

문제 해결

일반적인 문제

1. 연결 오류:

   • MySQL 서버가 실행 중인지 확인
   • 환경 변수가 올바르게 설정되었는지 확인
   • 로컬 설치 시 MySQL 클라이언트 라이브러리가 설치되어 있는지 확인

2. 쿼리 실행 오류:

   • SQL 구문 검사
   • 데이터베이스 권한 확인
   • 로컬 설치 시 MySQL 커넥터 버전 확인

로깅

서버는 기본적으로 로그를 표준 출력에 기록합니다. 로컬 설치 시 로그 레벨을 조정하려면:

python mcp_server.py --log-level DEBUG

Docker를 사용하는 경우 로그를 확인하려면:

docker logs [container-id]

기여하기

1. 이슈 생성
2. 브랜치 생성 (git checkout -b feature/AmazingFeature)
3. 변경사항 커밋 (git commit -m 'Add some AmazingFeature')
4. 브랜치 푸시 (git push origin feature/AmazingFeature)
5. Pull Request 생성

라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

연락처

문의사항이 있으시면 이슈를 생성해주세요.