Content
# Tool List
<p align="center">
<img alt="Python版本" src="https://img.shields.io/badge/Python-3.8%2B-blue">
<img alt="数据库支持" src="https://img.shields.io/badge/Database-MySQL%2C%20PostgreSQL%2C%20SQLite%2C%20SQL%20Server%2C%20MongoDB-green">
<img alt="AI集成" src="https://img.shields.io/badge/AI-OpenAI%2FDeepSeek-orange">
</p>
> A universal interface for interacting with multiple databases using natural language, built on the Model Context Protocol (MCP)
DB-MCP is an innovative database interaction framework that supports interacting with multiple databases (MySQL, PostgreSQL, SQLite, SQL Server, MongoDB) through natural language. It integrates large language model (LLM) capabilities, enabling non-technical personnel to easily perform complex database operations.
<br/>
## ✨ Core Features
- **Unified Multi-Database Interface**: Connect to different types of databases and perform cross-database operations
- **AI-Driven Queries**: Generate SQL statements and interpret results using natural language
- **Flexible Transmission Protocol**: Supports multiple MCP transmission protocols, such as stdio and sse
- **Multi-LLM Providers**: Compatible with AI services like OpenAI and DeepSeek
- **Out-of-the-Box**: Built-in demonstration database for quick experience
- **Rich Toolset**: Integrated database browsing, query execution, and data export
<br/>
## 🧩 System Architecture
```mermaid
graph LR
subgraph Client
C[User Interface] --> MCP[MCP Client]
MCP --> LLM[LLM API Interaction]
end
subgraph Server
MCP --> S[MCP Server]
S --> DB1[(MySQL)]
S --> DB2[(PostgreSQL)]
S --> DB3[(SQLite)]
S --> DB4[(SQL Server)]
S --> DB5[(MongoDB)]
end
LLM -.-> AI[OpenAI/DeepSeek]
Client -- MCP Protocol --> Server
```
<br/>
## ⚙️ Installation Guide
### Prerequisites
- Python 3.8+
- Database drivers (install as needed):
- MySQL: `aiomysql`
- PostgreSQL: `asyncpg`
- SQLite: `aiosqlite`
- SQL Server: `pyodbc`, `aioodbc`
### Quick Installation
```bash
# 1. Clone the repository
git clone https://github.com/Ouniel/db-mcp.git
cd db-mcp
# 2. Install dependencies
pip install -r requirements.txt
# 3. Configure environment
cp config/example.env .env
# Edit .env file to set API keys and database connections
```
<br/>
## 🚀 Usage Guide
### Server Mode
Start MCP server to connect to databases:
```bash
# Use demonstration database (quick experience)
python main.py server --demo
# Connect to MySQL database
python main.py server --dsn "mysql://user:password@localhost:3306/dbname"
# Multiple database connections (cross-database operations)
python main.py server \
--dsn "mysql://user:password@localhost:3306/mysql_db" \
--dsn "postgres://user:password@localhost:5432/postgres_db" \
--dsn "sqlite:///data/app.db"
# Use SSE protocol (web application integration)
python main.py server --transport sse --port 8080
# Specify AI provider
python main.py server --ai-provider deepseek --ai-api-key "your-api-key"
```
### Client Mode
Connect to MCP server for interaction:
```bash
# Basic client
python main.py client
# Custom configuration
python main.py client --config config/prod.json
# Specify LLM provider
python main.py client --llm-provider openai --llm-api-key "sk-..."
```
<br/>
## 🔌 Database Connection Format
| Database Type | Connection String Format | Example |
|------------|----------------|------|
| **MySQL** | `mysql://user:password@host:port/dbname` | `mysql://admin:pass123@localhost:3306/employees` |
| **PostgreSQL** | `postgres://user:password@host:port/dbname?param=value` | `postgres://user:pass@db.example.com:5432/sales?sslmode=require` |
| **SQLite** | `sqlite:///path/to/file.db` | `sqlite:///data/app.db` |
| **SQL Server** | `sqlserver://user:password@host:port/dbname` | `sqlserver://sa:Password!@sqlserver:1433/master` |
| **MongoDB** | `mongodb://user:password@host:port/dbname` | `mongodb://mongo_user:pass@mongo:27017/logs` |
<br/>
## 💬 Natural Language Interaction Example
```plaintext
User: List all product tables
AI: [Display all product tables across databases]
User: What is the structure of the customers table in mysql_db?
AI: [Show MySQL customers table structure]
User: Query the top 5 electronic products by price
AI: [Execute query and display results]
User: Generate SQL query for recent orders from New York customers
AI:
SELECT * FROM orders
WHERE customer_id IN (
SELECT id FROM customers
WHERE city = 'New York'
)
ORDER BY order_date DESC
LIMIT 10;
User: Compare the number of users in mysql_db and postgres_db
AI:
MySQL users: 1,245
PostgreSQL users: 987
Difference: +258 (26.1%)
User: Import product data from MongoDB into SQLite
AI: [Execute data migration operation]
```
<br/>
## 🛡️ Security and Best Practices
<details>
<summary><b>Security Considerations</b></summary>
1. **API Key Protection**:
- Never submit API keys to version control systems
- Use `.env` files to manage sensitive information
- Rotate API keys regularly
2. **Database Permissions**:
```sql
-- Create dedicated database user
CREATE USER 'mcp_user'@'localhost' IDENTIFIED BY 'strong_password';
-- Limit permissions
GRANT SELECT ON employees.* TO 'mcp_user'@'localhost';
```
3. **Production Environment Configuration**:
- Use SSL/TLS to encrypt database connections
- Enable firewall to restrict access IPs
- Regularly audit query logs
</details>
<details>
<summary><b>Performance Optimization</b></summary>
1. **Query Limitations**:
```bash
# Set maximum returned rows
python main.py server --max-rows 100
```
2. **Cache Strategy**:
- Enable query result caching
- Set reasonable cache expiration time
3. **Connection Pool Configuration**:
```python
# Configure in .env file
DB_MAX_CONNECTIONS=10
DB_TIMEOUT=30
```
</details>
<br/>
## ⚠️ Disclaimer
**Please read and agree to the following terms before using this tool:**
1. **Data Security**: Ensure you have legitimate permissions to operate the target database
2. **AI Risk**: LLM-generated query statements need human review before execution
3. **Production Environment**: Do not directly use AI-generated queries in production databases
4. **Sensitive Data**: Avoid processing unanonymized personal identifiable information (PII)
5. **Legal Compliance**: Comply with local data protection regulations (GDPR, CCPA, etc.)
The developer is not responsible for:
- Data damage caused by AI-generated queries
- Legal issues caused by unauthorized access
- Consequences of sensitive information leakage
- API usage violating service terms
<br/>
---
**Unlock database capabilities with natural language** - Make data interaction more intuitive and natural 💬
