# MySQL MCP 서버
[![smithery badge](https://smithery.ai/badge/@aqaranewbiz/mysql-aqaranewbiz)](https://smithery.ai/server/@aqaranewbiz/mysql-aqaranewbiz)
이 프로젝트는 Smithery의 Model Context Protocol (MCP)을 사용하여 MySQL 데이터베이스와 상호작용하는 서버입니다.

## Installation

### Installing via Smithery
To install MySQL Server for Claude Desktop automatically via Smithery:

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

### Manual Installation
```bash
npx @aqaranewbiz/mysql-aqaranewbiz
```

## Configuration

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

```json
{
  "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.

```javascript
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.

```javascript
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.

```javascript
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.

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

### 5. describe_table
Get the structure of a specific table.

```javascript
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` 파일 생성:
```env
MYSQL_HOST=your_mysql_host
MYSQL_USER=your_mysql_user
MYSQL_PASSWORD=your_mysql_password
MYSQL_DATABASE=your_database_name
```

### 설치 방법

#### 로컬 설치 (권장)

1. Python 가상환경 생성 및 활성화:
```bash
# Windows
python -m venv venv
venv\Scripts\activate

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

2. 의존성 설치:
```bash
pip install -r requirements.txt
```

3. 서버 실행:
```bash
python mcp_server.py
```

#### Docker 설치

1. Docker 이미지 빌드:
```bash
docker build -t mysql-mcp-server .
```

2. 컨테이너 실행:
```bash
docker run -e MYSQL_HOST=host -e MYSQL_USER=user -e MYSQL_PASSWORD=pass -e MYSQL_DATABASE=db mysql-mcp-server
```

### 로컬 개발 설정

1. 개발 환경 설정:
```bash
# 개발용 의존성 설치
pip install -r requirements-dev.txt  # 필요한 경우 생성

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

2. 코드 실행:
```bash
# 개발 모드로 실행
python mcp_server.py --dev
```

3. 테스트 실행:
```bash
# 테스트 실행
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 커넥터 버전 확인

### 로깅

서버는 기본적으로 로그를 표준 출력에 기록합니다. 로컬 설치 시 로그 레벨을 조정하려면:
```bash
python mcp_server.py --log-level DEBUG
```

Docker를 사용하는 경우 로그를 확인하려면:
```bash
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` 파일을 참조하세요.

## 연락처

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