Content
# MCP Multi-Database Connector
[](https://python.org)
[](https://github.com/)
[](LICENSE)
MCP (Model Context Protocol) multi-database connector, supporting Microsoft SQL Server and PostgreSQL. Through static schema preloading and intelligent analysis, AI accurately understands your database structure and business logic.
Use the `schemas_config/` directory to customize your business domain configuration.
---
```text
┌─────────────────────────────────────────────────────┐
│ Client Layer │
│ ┌──────────────┐ ┌──────────┐ ┌───────────────┐ │
│ │Claude Desktop│ │ Web Browser│ │ Third-party Apps │ │
│ └──────┬───────┘ └────┬─────┘ └───────┬───────┘ │
└─────────┼───────────────┼────────────────┼──────────┘
│ │ │
┌─────────┼───────────────┼────────────────┼──────────┐
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌─────────────────────────┐ │
│ │ MCP Server │ │ HTTP API Server │ │
│ │ (stdio) │ │ (FastAPI + OpenAPI) │ │
│ └──────┬───────┘ └───────────┬─────────────┘ │
│ │ Service Layer │ │
└─────────┼──────────────────────┼────────────────────┘
│ │
┌─────────┼──────────────────────┼────────────────────┐
│ ▼ ▼ │
│ ┌────────────────────────────────────────────┐ │
│ │ Unified Tool Processing Layer (Tools) │ │
│ │ db_query / db_schema / db_dependencies ... │ │
│ └──────────────────────┬──────────────────────┘ │
│ │ Core Layer │
│ ┌──────────┐ ┌────────┴────────┐ ┌────────────┐ │
│ │ Config Mgmt │ │ Database Mgr │ │ Error Handling │ │
│ │ (Config) │ │(DatabaseManager)│ │(Exceptions)│ │
│ └──────────┘ └────────┬────────┘ └────────────┘ │
└─────────────────────────┼───────────────────────────┘
│
┌─────────────────────────┼────────────────────────────┐
│ ▼ │
│ ┌──────────────┐ ┌──────────┐ ┌───────────────┐ │
│ │ Schema Cache │ │Schema │ │ Static Schema │ │
│ │(LFU+LRU+TTL) │ │ Inspector │ │ Loader(JSON) │ │
│ └──────────────┘ └────┬─────┘ └───────┬───────┘ │
│ Data Layer │ │ │
│ ┌─────────────┼────────────────┤ │
│ ▼ ▼ ▼ │
│ ┌────────────┐ ┌────────────┐ ┌───────────────┐ │
│ │ SQL Server │ │ PostgreSQL │ │schemas_config/│ │
│ │ (MSSQL) │ │ │ │ JSON Config File │ │
│ └────────────┘ └────────────┘ └───────────────┘ │
└──────────────────────────────────────────────────────┘
```
---
## Core Features
### Basic Capabilities
- **Multi-Database Support**: Native SQL Server and PostgreSQL connectors
- **10+ Database Tools**: Query, schema analysis, dependency analysis, export, etc.
- **Static Schema Preloading**: Inject business semantics through JSON configuration
- **Intelligent Cache**: LFU+Lru+TTL multi-layer cache, millisecond-level response
- **Relationship Analysis**: Table dependency and foreign key relationship analysis
### AI Enhancement
- **Schema-Aware AI**: Generate accurate SQL based on actual database structure and business semantics
- **Token Optimization**: Schema compression saves 60-80% token usage
- **SQL Syntax Guidance**: Automatically detect database type and provide corresponding syntax prompts
### Dual-Mode Architecture
- **Claude Desktop (MCP Protocol)**: Provide complete MCP tool support through stdio
- **Open WebUI (HTTP API)**: RESTful API + OpenAPI/Swagger documentation
---
## Quick Start
### Method 1: Claude Desktop (MCP Protocol)
**1. Prepare Environment**
```bash
git clone https://github.com/Bright0505/MCP_DB.git
cd MCP_DB
cp .env.example .env
# Edit .env to fill in database connection information
```
**2. Configure Claude Desktop**
Find the configuration file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"mcp-db": {
"command": "python",
"args": ["-m", "server"],
"cwd": "/path/to/MCP_DB/src",
"env": {
"DB_TYPE": "postgresql",
"DB_HOST": "localhost",
"DB_NAME": "your_database",
"DB_USER": "your_username",
"DB_PASSWORD": "your_password",
"DB_PORT": "5432",
"SCHEMA_ENABLE_CACHE": "true"
}
}
}
}
```
**3. Restart Claude Desktop and Test**
```bash
Please test the database connection status
```
### Method 2: HTTP API (Open WebUI)
```bash
# Docker deployment (recommended)
cp .env.example .env
# Edit .env
docker-compose up -d
# Or run locally
pip install -e .
python -m http_server
```
Access API documentation: http://localhost:8000/docs
### Example Usage
```bash
# Test connection
curl -X POST http://localhost:8000/api/test-connection
# Execute query
curl -X POST http://localhost:8000/api/query \
-H "Content-Type: application/json" \
-d '{"query": "SELECT TOP 10 * FROM ORDERS"}'
# View table schema
curl -X POST http://localhost:8000/api/schema \
-H "Content-Type: application/json" \
-d '{"table_name": "ORDERS"}'
```
---
## Environment Configuration
```bash
# Database type
DB_TYPE=postgresql # or mssql
# Database connection
DB_HOST=localhost
DB_NAME=your_database
DB_USER=your_username
DB_PASSWORD=your_password
DB_PORT=5432 # PostgreSQL: 5432, SQL Server: 1433
# Schema cache (recommended to enable)
SCHEMA_ENABLE_CACHE=true
SCHEMA_CACHE_TTL_MINUTES=60
# HTTP API
HTTP_HOST=0.0.0.0
HTTP_PORT=8000
```
---
## MCP Tool List
| Tool Name | Description |
|----------|------|
| `db_query` | Execute SELECT query (read-only mode) |
| `db_schema` | View table structure and field information |
| `db_schema_summary` | Database object summary statistics |
| `db_dependencies` | Analyze table dependency relationships |
| `db_test_connection` | Test database connection |
| `db_cache_stats` | View cache statistics |
| `db_cache_invalidate` | Clear cache |
| `db_schema_reload` | Reload schema configuration |
| `db_static_schema_info` | View static schema information |
| `db_export_schema` | Export table schema |
| `db_syntax_guide` | SQL syntax reference guide |
---
## Business Customization
This project is a **template**, and customization is done through the `schemas_config/` directory:
### Three-Layer Knowledge Injection Architecture
```bash
schemas_config/
├── tables_list.json # Table whitelist and global settings
├── global_patterns.json # Global field naming patterns (e.g., _ID$, _DATE$, _AMT$)
├── ai_enhancement.json # AI query enhancement (keyword mapping, query templates)
├── tables/ # Individual table detailed configuration
│ └── ORDERS.json # Field description, status value definition, JOIN suggestions
└── examples/
└── sample_table.json # Complete example reference
```
### Customization Steps
1. Register your tables in `schemas_config/tables_list.json`
2. Create detailed configurations for important tables in `schemas_config/tables/<TABLE>.json`
3. Configure AI query patterns in `schemas_config/ai_enhancement.json`
4. Refer to `schemas_config/examples/sample_table.json` for a complete example
Detailed guide: [schemas_config/README.md](schemas_config/README.md) | [Complete Configuration Manual](schemas_config/SCHEMA_CONFIG_GUIDE.md)
---
## Documentation Navigation
### Getting Started
- [MCP Quick Start](docs/MCP_QUICK_START.md) — Complete MCP feature guide (recommended)
- [Quick Start](docs/quick-start.md) — 5-minute getting started guide
- [Installation Guide](docs/installation.md) — Environment setup and installation steps
### Technical
- [System Architecture](docs/architecture.md) — Layered architecture design and module description
- [Schema System](docs/schema-system.md) — Static schema and JSON configuration
- [Performance Optimization](docs/performance.md) — Cache system and token optimization
### Development
- [Development Environment](docs/development/README.md) — Development history and contribution guide
- [Testing Guide](docs/testing.md) — Unit testing and coverage
- [Claude Code Settings](docs/CLAUDE.md) — Claude Code hooks and automation
---
## License
MIT License — See [LICENSE](LICENSE)
---
**Version**: v1.0.0
**Last Updated**: 2026-01-27
