Content
<div align="center">
<img src="https://raw.githubusercontent.com/XGenerationLab/XiYan-SQL/main/xiyanGBI.png" height="80" alt="XiYan Logo">
<h1>XiYan MCP Server</h1>
<p>
<b>Model Context Protocol (MCP) Server based on XiYanSQL framework</b>
</p>
<p>
Supports querying GreptimeDB, CockroachDB, MySQL, PostgreSQL, and other databases through natural language
</p>
<p>
<a href="https://opensource.org/licenses/Apache-2.0">
<img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache 2.0">
</a>
<a href="https://www.python.org/">
<img src="https://img.shields.io/badge/Python-3.13+-blue.svg" alt="Python 3.13+">
</a>
<a href="https://github.com/4iKZ/xiyan_mcp_server">
<img src="https://img.shields.io/github/stars/4iKZ/xiyan_mcp_server?style=social" alt="GitHub stars">
</a>
<a href="https://github.com/4iKZ/xiyan_mcp_server/releases">
<img src="https://img.shields.io/github/v/release/4iKZ/xiyan_mcp_server" alt="Release">
</a>
</p>
</div>
---
## Table of Contents
- [Project Overview](#project-overview)
- [Core Features](#core-features)
- [Installation](#installation)
- [Configuration](#configuration)
- [Start Service](#start-service)
- [API Usage](#api-usage)
- [Docker Deployment](#docker-deployment)
- [Available Tools](#available-tools)
- [Project Architecture](#project-architecture)
- [Main Differences from Original Project](#main-differences-from-original-project)
- [Schema Knowledge Base Management](#schema-knowledge-base-management)
- [Testing](#testing)
- [Frequently Asked Questions](#frequently-asked-questions)
- [Changelog](#changelog)
- [Open Source License](#open-source-license)
- [References](#references)
---
## Project Overview
This project is based on [XGenerationLab/xiyan_mcp_server](https://github.com/XGenerationLab/xiyan_mcp_server) with enhanced features:
- Supports GreptimeDB time-series database
- Supports CockroachDB distributed database
- Schema semantic filtering and lazy loading optimization
- Flexible Embedding model configuration (cloud API / local vLLM)
- Local vLLM model support
- Multi-format output (Markdown, JSON, CSV)
- SQL automatic repair mechanism (up to 5 retries)
## Core Features
### Database Support
- **GreptimeDB** (time-series database)
- **CockroachDB** (distributed relational database)
- **MySQL**
- **PostgreSQL**
- **SQLite**
### Model Support
- **General LLMs** (GPT, Qwen-Max, etc.)
- **XiYanSQL-QwenCoder** series models
- **Local vLLM** deployment models
### Performance Optimization
- Redis semantic Schema retrieval
- Column information lazy loading
- Global database connection pool (supporting high-concurrency queries)
- Basic connection pool size: 10
- Maximum extra connections: 20
- Total supported concurrent database connections: 30
- Automatic connection recycling and health check
- SQL automatic error repair
- Multi-threaded safety design (supporting SQLite concurrent access)
## Installation
### System Requirements
- Python 3.13+
- Redis (optional, for schema filtering)
### Method 1: Install from Source
```bash
# Clone repository
git clone https://github.com/4iKZ/xiyan_mcp_server.git
cd xiyan_mcp_server
# Install dependencies
pip install -e .
```
### Method 2: Install from Release
```bash
# Download specific version source code
wget https://github.com/4iKZ/xiyan_mcp_server/archive/refs/tags/v0.1.5.tar.gz
tar -xzf v0.1.5.tar.gz
cd xiyan_mcp_server-0.1.5
# Install dependencies
pip install -e .
```
## Configuration
Edit `src/xiyan_mcp_server/config.yml`:
### Basic Configuration
```yaml
model:
name: "/share/modelscope/XiYanSQL-QwenCoder-14B-2504"
key: "not-needed"
url: "http://10.0.0.8:10000/v1/"
database:
system: "cockroach" # Optional: greptimedb, mysql, postgresql, sqlite
dialect: "greptimedb" # Database dialect
host: "10.0.0.8"
port: 4003
user: "root"
password: ""
database: "public"
schema_filter:
enabled: true
knowledge_dir: "json"
top_k: 5
score_threshold: 0.4
```
**Important**: The `json/` directory must contain JSON format documentation for database schema; otherwise, semantic retrieval functionality will not work. These documents need to be manually written or generated through scripts.
### Redis Configuration
host: "localhost"
port: 6379
password: ""
index_name: "xiyan_schema"
```
### Concurrency Configuration (optional)
Database connection pool configuration is modified in `src/xiyan_mcp_server/utils/db_util.py`:
```python
POOL_CONFIG = {
"pool_size": 10, # Basic connection number
"max_overflow": 20, # Maximum extra connections
"pool_timeout": 30, # Connection timeout (seconds)
"pool_recycle": 3600, # Connection recycling time (seconds)
"pool_pre_ping": True, # Connection health check
}
```
**Description**:
- Default support for up to 30 concurrent database connections
- Suitable for high-concurrency scenarios
- Automatic recycling of idle connections to avoid connection leaks
### Embedding Configuration (important)
**Note: After switching the embedding model, you must regenerate the Redis index:**
```bash
python scripts/index_knowledge.py --config src/xiyan_mcp_server/config.yml --rebuild
```
#### Option 1: Cloud ModelScope API (recommended)
Full-precision model, best effect:
```yaml
embedding:
model: "Qwen/Qwen3-Embedding-8B"
use_api: true
api_key: "your-modelscope-api-key"
vector_dim: 4096
```
#### Option 2: Local vLLM API
Need to deploy embedding model yourself:
```yaml
embedding:
model: "Qwen/Qwen3-Embedding-8B"
use_api: true
use_vllm_format: true
api_url: "http://localhost:10001/v1/"
api_key: "not-needed"
vector_dim: 4096
```
**Notes:**
- Using 4bit quantization may lead to reduced vector distinguishability; it is recommended to use FP16/BF16 quantization
- Cloud API will automatically add `encoding_format="float"` parameter to obtain full-precision vectors
## Start Service
### Method 1: Direct Start
```bash
# stdio mode (default)
python -m xiyan_mcp_server
# HTTP mode
python -m xiyan_mcp_server streamable-http --host 0.0.0.0 --port 8000
# SSE mode
python -m xiyan_mcp_server sse --host 0.0.0.0 --port 8000
```
### Method 2: Systemd Service
```bash
systemctl start xiyan-mcp-server
systemctl status xiyan-mcp-server
```
### Method 3: View Logs
```bash
tail -f /tmp/xiyan_server.log
```
## API Usage
### Initialize Session
```python
import requests
base_url = "http://localhost:8000/mcp"
headers = {
"Content-Type": "application/json",
"Accept": "application/json, text/event-stream"
}
# Initialize
init_request = {
"jsonrpc": "2.0",
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {},
"clientInfo": {"name": "test-client", "version": "1.0"}
},
"id": 1
}
resp = requests.post(base_url, headers=headers, json=init_request, timeout=60)
session_id = resp.headers.get("Mcp-Session-Id")
```
### Query Data
```python
headers["Mcp-Session-Id"] = session_id
call_request = {
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "get_data",
"arguments": {
"query": "Query the average memory usage of the database cluster in the last 5 hours",
"format": "markdown" # markdown, json, csv
}
},
"id": 2
}
resp = requests.post(base_url, headers=headers, json=call_request, timeout=300)
```
## Docker Deployment
### Method 1: Using Docker Command
```bash
# Build image
docker build -t xiyan-mcp-server .
# Run container (stdio mode)
docker run -v $(pwd)/src/xiyan_mcp_server/config.yml:/app/src/xiyan_mcp_server/config.yml \
xiyan-mcp-server
# Run container (HTTP mode)
docker run -p 8000:8000 \
-v $(pwd)/src/xiyan_mcp_server/config.yml:/app/src/xiyan_mcp_server/config.yml \
xiyan-mcp-server \
python -m xiyan_mcp_server streamable-http --host 0.0.0.0
```
### Method 2: Using Docker Compose (recommended)
```bash
# Start service
docker-compose up -d
# View logs
docker-compose logs -f xiyan-mcp-server
# Stop service
docker-compose down
```
**Hint**: Edit `docker-compose.yml` to:
- Switch transmission mode (stdio/HTTP/SSE)
- Add Redis and GreptimeDB dependency services
- Configure environment variables
## Available Tools
### get_data
Query database through natural language and return results.
Parameters:
- `query` (required): Natural language query question
- `format` (optional): Output format
- `markdown`: Table format (default)
- `json`: JSON format
- `csv`: CSV format
## Project Architecture
```
src/xiyan_mcp_server/
├── server.py # MCP service entry
├── database_env.py # Database environment encapsulation
├── config.yml # Configuration file
├── config.example.yml # Configuration file template
└── utils/
├── db_util.py # Database connection pool
├── llm_util.py # LLM API call
├── schema_retriever.py # Schema retrieval
├── embedding_service.py # Embedding service (supporting cloud/local)
├── db_source.py # Database metadata
└── greptimedb_source.py # GreptimeDB support
scripts/
└── index_knowledge.py # Schema knowledge base indexing tool
json/ # Schema knowledge base directory
```
## Main Differences from Original Project
1. **GreptimeDB Support**: Added GreptimeDB dialect and dedicated data source
2. **CockroachDB Support**: Complete support for CockroachDB distributed database
3. **Schema Optimization**: Redis-based semantic retrieval + lazy loading
4. **Local Model**: Complete support for local vLLM deployment
5. **Output Format**: Supports Markdown/JSON/CSV three formats
6. **Error Handling**: Enhanced SQL repair logic (5 retries)
7. **Configuration Separation**: Embedding and main model configuration separation
8. **Embedding Flexibility**: Supports cloud API and local vLLM deployment
## Schema Knowledge Base Management
**Important Note**: This project relies on database schema explanation documents in the `json/` directory. These documents can be:
1. **Manually created**: Manually write table and column descriptions in JSON format
2. **Automatically generated by script**: Use database scripts to automatically extract schema information
If the `json/` directory is empty or lacks relevant documents, the schema semantic retrieval functionality will not work properly. Ensure that these documents are prepared before use.
### Initial Indexing
Index database schema information from `json/` directory into Redis:
```bash
python scripts/index_knowledge.py --config src/xiyan_mcp_server/config.yml
```
### Rebuild Index
**Note: Rebuild index in the following situations:**
- Switch embedding model (cloud API ↔ local vLLM)
- Change embedding model version
- Modify database schema structure
- Adjust vector dimension configuration
```bash
python scripts/index_knowledge.py --config src/xiyan_mcp_server/config.yml --rebuild
```
### Check Schema
This project does not require an independent check script. Verify schema configuration correctness by:
- Starting MCP server and reading `greptimedb://<database>` resources to view complete schema
- Enabling schema_filter and observing filtered_table_names field in query_tracker logs
- Offline analysis: Use `scripts/analyze_judge_results.py` to evaluate SQL generation quality
Refer to `docs/dev-guide/EXPERIMENT_COMMANDS.md` for corresponding commands.
## Testing
```bash
# General testing
python test.py
# Natural language query testing
python test_natural_language_queries.py
# CockroachDB testing
python test_cockroachdb.py
```
## Frequently Asked Questions
### 1. Python Version Requirements
This project requires Python 3.13 or higher.
### 2. Redis Connection Failure
Ensure Redis service is running:
```bash
# Check Redis status
systemctl status redis
# Start Redis
systemctl start redis
```
### 3. Embedding Model Switching
After switching the embedding model, you must regenerate the Redis index; otherwise, it will affect retrieval effectiveness.
### 4. Docker Container Cannot Access Database
Ensure container network can access database service; use `docker network` or `--network host` mode.
### 5. Concurrency Limit
Default database connection pool supports up to 30 concurrent connections. If higher concurrency is needed, modify `src/xiyan_mcp_server/utils/db_util.py` `POOL_CONFIG`:
```python
"pool_size": 20, # Increase basic connections
"max_overflow": 30, # Increase maximum extra connections
```
**Note**: Increase connections require ensuring database server can handle corresponding number of concurrent connections.
### 6. Connection Pool Exhaustion
If connection pool exhaustion error occurs, possible reasons:
- Excessive concurrent requests exceed maximum connections
- Connections not released properly (code bug)
- Long database query time
**Solution**:
- Increase connection pool size
- Optimize slow queries
- Check code for connection leaks
### 7. Empty or Missing json Directory
If `json/` directory is empty or lacks database schema documents, schema semantic retrieval functionality will not work properly.
**Solution**:
1. Manually create JSON format database schema documents
2. Use database scripts to automatically generate schema documents
3. Ensure documents contain table name, column name, data type, and business description information
## Changelog
## Open Source License
## References
### v0.1.5 (2025-02-05) - Beta
**New Features**
- Support for GreptimeDB time-series database
- Support for CockroachDB distributed database
- Schema semantic filtering and lazy loading optimization
- Data desensitization processing
**Optimization and Improvement**
- Fix Async function blocking issue
- Improve .gitignore configuration
- Update Python version requirement to 3.13
- Optimize dependency version management
**Docker Support**
- Rewrite Dockerfile to support Python 3.13
- Add .dockerignore file
- Add docker-compose.yml configuration
## Open Source License
This project is open-sourced under the Apache 2.0 license.
## Acknowledgements and Original Author
This project is based on [XGenerationLab/xiyan_mcp_server](https://github.com/XGenerationLab/xiyan_mcp_server) for transformation.
Thanks to all contributors of the original project:
- XGenerationLab
- ahmedmustahid
- YifuLiu-L
- eltociear
- lwsinclair
- Matvey-Kuk
- willyomg
- ZhuangbilityY
The original project technical support comes from [XiYan-SQL](https://github.com/XGenerationLab/XiYan-SQL) framework.
## Citation
If you use this project in your research, please cite:
```bibtex
@article{XiYanSQL,
title={XiYan-SQL: A Novel Multi-Generator Framework For Text-to-SQL},
author={Yifu Liu and Yin Zhu and Yingqi Gao and Zhiling Luo and Xiaoxia Li and Xiaorong Shi and Yuntao Hong and Jinyang Gao and Yu Li and Bolin Ding and Jingren Zhou},
year={2025},
eprint={2507.04701},
archivePrefix={arXiv},
primaryClass={cs.CL},
url={https://arxiv.org/abs/2507.04701},
}
```
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available