MySQL Hub MCP Server

MySQL 데이터베이스와 자연어 쿼리를 지원하는 MCP(Model Context Protocol) 서버입니다. HTTP 기반 통신과 MCP stdio 프로토콜을 모두 지원합니다.

📋 목적

Cursor AI에서 MCP를 통해 MySQL DB서버에 연결
Cursor AI chat 창에서 MySQL에 자연어로 데이터를 검색
HTTP API를 통한 직접적인 데이터베이스 조작
자연어를 SQL로 변환하는 AI 기반 쿼리 시스템

🏗️ 프로젝트 구조

mysql-hub-mcp/
├── client/                 # HTTP 기반 MCP 클라이언트 애플리케이션
│   ├── client_app.py      # httpx 기반 클라이언트 메인 애플리케이션
│   ├── run_client.py      # 클라이언트 실행 스크립트
│   └── pyproject.toml     # 클라이언트 의존성
├── server/                # MCP 서버 및 HTTP 서버
│   ├── server_app.py      # 서버 메인 애플리케이션
│   ├── mcp_server.py      # MCP 서버 구현
│   ├── http_server.py     # FastAPI 기반 HTTP API 서버
│   ├── database.py        # MySQL 데이터베이스 관리 (UTF-8 처리 포함)
│   ├── ai_provider.py     # AI Provider 관리 (Groq/Ollama)
│   ├── config.py          # 설정 관리
│   ├── run_server.py      # 서버 실행 스크립트
│   ├── env.example        # 환경 설정 예제
│   └── pyproject.toml     # 서버 의존성
├── bridge/                # Cursor MCP Bridge
│   ├── mcp_bridge.py      # Cursor Bridge 구현
│   └── pyproject.toml     # Bridge 의존성
├── docs/                  # 문서
│   └── requirement.md     # 요구사항 문서
├── pyproject.toml         # 프로젝트 루트 설정
└── README.md             # 프로젝트 설명서

🚀 설치 및 설정

1. 의존성 설치

각 컴포넌트별로 의존성을 설치합니다:

# 서버 의존성 설치
cd server
uv sync

# 클라이언트 의존성 설치
cd ../client
uv sync

# Bridge 의존성 설치
cd ../bridge
uv sync

2. 환경 설정

서버 디렉토리에 .env 파일을 생성하고 설정합니다:

cd server
cp env.example .env

.env 파일을 편집하여 다음 설정을 구성합니다:

# MySQL 데이터베이스 설정
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=devuser
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=devdb

# AI Provider 설정 (groq 또는 ollama)
AI_PROVIDER=ollama

# Groq 설정
GROQ_API_KEY=your_groq_api_key
GROQ_MODEL=llama3-8b-8192

# Ollama 설정
OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=llama3:8b

# 로깅 설정
LOG_LEVEL=INFO
LOG_FORMAT=%(asctime)s - %(name)s - %(levelname)s - %(message)s

# 서버 설정
SERVER_HOST=localhost
SERVER_PORT=8000

🎯 사용법

1. 서버 실행

HTTP 서버만 실행 (권장)

cd server
uv run run_server.py --mode http

HTTP 서버와 MCP 서버 동시 실행

cd server
uv run run_server.py

MCP 서버만 실행

cd server
uv run run_server.py --mode mcp

2. 클라이언트 실행

웹 인터페이스 (권장)

cd client
uv run run_web_client.py

웹 브라우저에서 http://localhost:8501로 접속하여 사용할 수 있습니다.

주요 기능:

🤖 자연어로 데이터베이스 질문
⚡ 직접 SQL 쿼리 실행
📋 데이터베이스 정보 조회
📊 테이블 스키마 확인
📊 결과를 표 형태로 시각화

대화형 모드 (터미널)

cd client
uv run run_client.py

배치 모드 - 자연어 쿼리

cd client
uv run run_client.py --tool natural_language_query --question "사용자 테이블에서 모든 데이터를 조회해주세요"

배치 모드 - SQL 실행

cd client
uv run run_client.py --tool execute_sql --sql "SELECT * FROM users"

도구 목록 확인

cd client
uv run run_client.py --list-tools

3. Bridge 실행 (테스트용)

cd bridge
uv run mcp_bridge.py --question "사용자 테이블에서 모든 데이터를 조회해주세요"

🔧 제공되는 도구

1. execute_sql

설명: MySQL 데이터베이스에서 SQL 쿼리를 실행합니다.
매개변수: sql (실행할 SQL 쿼리)
예시: SELECT * FROM users WHERE user_name = '홍길동'

2. natural_language_query

설명: 자연어를 SQL 쿼리로 변환하여 실행합니다.
매개변수: question (자연어로 된 질문)
예시:
- "노트북을 주문한 사용자의 이름과 이메일을 조회해주세요"
- "가장 많이 주문한 사용자를 찾아주세요"
- "각 사용자별로 주문한 상품과 금액을 보여주세요"

3. get_database_info

설명: 데이터베이스 정보와 테이블 목록을 반환합니다.
매개변수: 없음

4. get_table_schema

설명: 특정 테이블의 스키마 정보를 반환합니다.
매개변수: table_name (테이블 이름)

🌐 HTTP API

서버가 실행되면 다음 HTTP API를 사용할 수 있습니다:

기본 엔드포인트

GET / - 서버 상태 확인
GET /health - 헬스 체크

데이터베이스 엔드포인트

GET /database/info - 데이터베이스 정보
POST /database/execute - SQL 쿼리 실행
POST /database/natural-query - 자연어 쿼리 실행
GET /database/tables - 테이블 목록
POST /database/table-schema - 테이블 스키마

AI Provider 엔드포인트

GET /ai/provider - 현재 AI Provider 정보
POST /ai/switch-provider - AI Provider 전환

🤖 AI Provider

Groq

특징: 빠른 응답 속도, 클라우드 기반
설정: AI_PROVIDER=groq
필요: API 키 설정

Ollama

특징: 로컬 실행 가능, 오프라인 사용 가능
설정: AI_PROVIDER=ollama
필요: Ollama 서버 실행 (기본: http://localhost:11434)

📊 실제 테스트 결과

성공적인 쿼리 실행 예시

직접 SQL 실행 (권장 방법)

-- 사용자 정보 조회
SELECT * FROM users ORDER BY id;
결과: 3명의 사용자 정보 (홍길동, 이순신, 세종대왕)

-- 특정 이메일 사용자 조회
SELECT user_name, signup_date FROM users WHERE email = 'gildong@example.com';
결과: 홍길동, 2024-01-15

-- 노트북 주문 사용자 조회
SELECT u.user_name, u.email FROM users u INNER JOIN orders o ON u.id = o.user_id WHERE o.product_name LIKE '%노트북%';
결과: 홍길동, gildong@example.com

-- 가장 비싼 상품 주문자 조회
SELECT u.user_name, o.product_name, o.amount FROM users u INNER JOIN orders o ON u.id = o.user_id WHERE o.amount = (SELECT MAX(amount) FROM orders);
결과: 홍길동, 노트북, 1,500,000원

-- 특정 날짜 이후 주문 상품 조회
SELECT product_name FROM orders WHERE order_date > '2024-07-05' ORDER BY order_date;
결과: 집현전 대형 책상, 거북선 모양 USB

자연어 쿼리 실행 (대안 방법)

# 기본 조회
질문: "사용자 테이블에서 모든 데이터를 조회해주세요"
생성된 SQL: SELECT * FROM users;
결과: 3명의 사용자 정보 (홍길동, 이순신, 세종대왕)

# 조건부 조회
질문: "노트북을 주문한 사용자의 이름과 이메일을 조회해주세요"
생성된 SQL: SELECT DISTINCT u.user_name, u.email FROM users u JOIN orders o ON u.id = o.user_id WHERE o.product_name = '노트북';
결과: 노트북을 주문한 사용자 정보

# 복잡한 JOIN 쿼리
질문: "가장 비싼 상품을 주문한 사용자의 이름과 상품명을 조회해주세요"
생성된 SQL: SELECT u.user_name, o.product_name FROM orders o JOIN users u ON o.user_id = u.id WHERE o.amount = (SELECT MAX(amount) FROM orders);
결과: 최고가 주문 정보

🛡️ 오류 처리 및 안정성

UTF-8 인코딩 처리

바이너리 데이터를 16진수 문자열로 자동 변환
제어 문자 자동 제거
마크다운 코드 블록 자동 제거

AI 응답 검증

오류 메시지 감지 및 차단
SQL 키워드 검증
타임아웃 처리 (60초)

데이터베이스 연결

연결 풀링 및 자동 재연결
UTF-8 인코딩 강제 설정
쿼리 유효성 검사

MCP Bridge 파라미터 수정

execute_sql 함수의 파라미터명을 query에서 sql로 수정
FastMCP 프레임워크와의 호환성 개선
직접 SQL 실행 기능 안정화

📝 로깅

로그는 다음 위치에 저장됩니다:

콘솔 출력
logs/server-YYYYMMDD.log (서버 로그)
logs/client-YYYYMMDD.log (클라이언트 로그)

로그 파일 특징

날짜별 분리: 매일 새로운 로그 파일 생성
UTF-8 인코딩: 한글 로그가 깨지지 않음
자동 디렉토리 생성: logs 폴더가 없으면 자동 생성

로그 레벨은 환경 변수 LOG_LEVEL로 설정할 수 있습니다:

DEBUG: 상세한 디버깅 정보
INFO: 일반적인 정보 (기본값)
WARNING: 경고 메시지
ERROR: 오류 메시지

🔗 Cursor AI 연동

Cursor AI에서 이 MCP 서버를 사용하려면:

Cursor AI 설정에서 MCP 서버를 추가
MCP Server 등록

"mcpServers": {
  "mysql-hub-mcp": {
    "command": "uv",
    "args": [
      "--directory",
      "D:\\workspaces\\mcp-work\\mysql-hub-mcp\\bridge",
      "run",
      "mcp_bridge.py",
      "--url",
      "http://localhost:8000"
    ]
  }
}

Cursor AI chat에서 자연어로 데이터베이스 질문 가능

Cursor Rules 설정

효율적인 SQL 쿼리 실행을 위해 Cursor Rules를 설정하는 것을 권장합니다:

.cursor/rules/ 디렉토리에 mysql-hub-mcp-rule.mdc 파일 생성
다음 규칙 추가:

# MySQL Hub MCP 사용 규칙

## SQL 쿼리 실행 우선순위

### 1단계: 직접 SQL 작성 (권장)
- `mysql-hub-mcp`를 사용할 때는 즉시 `natural_language_query()`를 호출하지 않음
- 다음 순서로 진행:
  1. `get_database_info()` - 데이터베이스 정보 및 테이블 목록 확인
  2. `get_table_schema(table_name)` - 관련 테이블의 스키마 정보 확인
  3. 스키마 정보를 바탕으로 직접 SQL 문 작성
  4. `execute_sql(sql)` - 작성한 SQL 직접 실행

### 2단계: 자연어 쿼리 (대안)
- 위 방법으로 SQL을 작성할 수 없는 경우에만 `natural_language_query()` 사용
- 복잡한 쿼리나 스키마 정보만으로는 SQL 작성이 어려운 경우

## 목적
- 더 빠르고 정확한 SQL 실행
- 불필요한 자연어 변환 과정 최소화
- 데이터베이스 구조 이해를 통한 효율적인 쿼리 작성

🛠️ 개발 환경

개발도구: Cursor IDE
개발언어: Python 3.10+
패키지 관리: uv
웹 프레임워크: FastAPI
HTTP 클라이언트: httpx
데이터베이스: MySQL + SQLAlchemy
AI 통합: Groq API, Ollama
대화 언어: 한국어 (보조적으로 영어 사용 가능)

🔧 주요 기술 스택

백엔드: FastAPI, SQLAlchemy, PyMySQL
AI/ML: Groq API, Ollama
통신: HTTP/HTTPS, MCP Protocol
로깅: Python logging
UI: Rich (터미널 UI), Streamlit (웹 UI)
설정: python-dotenv
MCP: FastMCP, Model Context Protocol

📚 참고 문서

🤝 기여

이 프로젝트는 학습 목적으로 개발되었습니다. 개선 사항이나 버그 리포트는 언제든 환영합니다.

📄 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다.

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A Model Context Protocol server that enables natural language querying of MySQL databases, supporting both HTTP-based communication and MCP stdio protocol.

Related MCP Servers

MySQL-MCP
zajTools
-
security
F
license
-
quality
A Model Context Protocol server that enables SQL query execution, database management, and business intelligence capabilities through MySQL connections.
Last updated -
JavaScript
XiYan MCP Server
XGenerationLab
-
security
A
license
-
quality
A Model Context Protocol server that enables natural language queries to MySQL databases, powered by XiYanSQL text-to-SQL technology.
Last updated -
190
Python
Apache 2.0
MCP MySQL Server
kevinbin
A
security
F
license
A
quality
A Model Context Protocol server that enables AI models to interact with MySQL databases through a standardized interface, providing tools for querying, executing commands, and managing database schemas.
Last updated -
7
JavaScript
MySQL MCP Server
caicongyang
-
security
F
license
-
quality
A Model Context Protocol server that enables AI models to interact with MySQL databases through natural language, supporting SQL queries, table creation, and schema exploration.
Last updated -
3
Python

View all related MCP servers