Uses python-dotenv for configuration management, allowing users to customize database connections, AI providers, and server settings through environment variables.
Provides a REST API interface for database operations, allowing HTTP-based access to all database querying capabilities through dedicated endpoints.
Enables querying MySQL databases using both direct SQL execution and natural language queries, with support for retrieving database information, table schemas, and executing complex SQL operations.
Integrates with Ollama for local AI model execution to convert natural language queries into SQL, offering offline database query capabilities through local LLM inference.
Utilizes Rich for enhanced terminal UI with improved formatting and visual presentation of database query results in the command-line interface.
Leverages SQLAlchemy for database connection pooling, query execution, and ORM capabilities to interact with MySQL databases safely and efficiently.
Offers a web-based user interface for interacting with the database, visualizing query results, and providing a graphical alternative to command-line operations.
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 기반 쿼리 시스템
🏗️ 프로젝트 구조
🚀 설치 및 설정
1. 의존성 설치
각 컴포넌트별로 의존성을 설치합니다:
2. 환경 설정
서버 디렉토리에 .env
파일을 생성하고 설정합니다:
.env
파일을 편집하여 다음 설정을 구성합니다:
🎯 사용법
1. 서버 실행
HTTP 서버만 실행 (권장)
HTTP 서버와 MCP 서버 동시 실행
MCP 서버만 실행
2. 클라이언트 실행
웹 인터페이스 (권장)
웹 브라우저에서 http://localhost:8501
로 접속하여 사용할 수 있습니다.
주요 기능:
- 🤖 자연어로 데이터베이스 질문
- ⚡ 직접 SQL 쿼리 실행
- 📋 데이터베이스 정보 조회
- 📊 테이블 스키마 확인
- 📊 결과를 표 형태로 시각화
대화형 모드 (터미널)
배치 모드 - 자연어 쿼리
배치 모드 - SQL 실행
도구 목록 확인
3. Bridge 실행 (테스트용)
🔧 제공되는 도구
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 실행 (권장 방법)
자연어 쿼리 실행 (대안 방법)
🛡️ 오류 처리 및 안정성
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 등록
- Cursor AI chat에서 자연어로 데이터베이스 질문 가능
Cursor Rules 설정
효율적인 SQL 쿼리 실행을 위해 Cursor Rules를 설정하는 것을 권장합니다:
.cursor/rules/
디렉토리에mysql-hub-mcp-rule.mdc
파일 생성- 다음 규칙 추가:
🛠️ 개발 환경
- 개발도구: 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
📚 참고 문서
- MCP Specification
- MCP Quickstart
- FastAPI Documentation
- SQLAlchemy Documentation
- FastMCP Documentation
- Cursor AI Documentation
🤝 기여
이 프로젝트는 학습 목적으로 개발되었습니다. 개선 사항이나 버그 리포트는 언제든 환영합니다.
📄 라이선스
이 프로젝트는 MIT 라이선스 하에 배포됩니다.
This server cannot be installed
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
- -securityFlicense-qualityA Model Context Protocol server that enables SQL query execution, database management, and business intelligence capabilities through MySQL connections.Last updated -JavaScript
- -securityAlicense-qualityA Model Context Protocol server that enables natural language queries to MySQL databases, powered by XiYanSQL text-to-SQL technology.Last updated -190PythonApache 2.0
- AsecurityFlicenseAqualityA 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 -7JavaScript
- -securityFlicense-qualityA 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 -3Python