db-mcp

# DB-MCP: General Database MCP Server and Client DB-MCP is a general database server and client based on the Model Context Protocol (MCP), supporting connections to various databases, including MySQL, PostgreSQL, SQLite, SQL Server, and MongoDB. It allows for natural language interaction with databases using the OpenAI or DeepSeek API. ## Features - Supports multiple databases: MySQL, PostgreSQL, SQLite, SQL Server, MongoDB - Allows simultaneous connections to multiple different types of databases and cross-database operations within a single session - Supports various MCP transport protocols: stdio, sse - Compatible with multiple LLM providers: OpenAI, DeepSeek - Built-in demo database for quick start - Provides database browsing, querying, exporting, and other functionalities - Supports AI-driven SQL generation and database explanation ## System Architecture ``` +---------------------+ +------------------+ | | | | | Client Program | | MCP Server | | +--------------+ | | | | | MCP Client Component |<--+--- MCP Protocol ------>| | | +--------------+ | | | | | | | | | v | | | | +--------------+ | | | | | LLM API Interaction | | | | | +--------------+ | | | | | | | | +---------------------+ +-------+----------+ | v +-----------------+ | | | Various Databases | | MySQL | | PostgreSQL | | SQLite | | SQL Server | | MongoDB | | | +-----------------+ ``` ## Installation ### Requirements - Python 3.8+ - Database drivers (as needed): - MySQL: aiomysql - PostgreSQL: asyncpg - SQLite: aiosqlite - SQL Server: pyodbc, aioodbc - Other dependencies: - mcp: MCP Protocol - openai: OpenAI API - httpx: HTTP Client - python-dotenv: Environment Variables ### Installation Steps 1. Clone the repository ``` git clone https://github.com/yourusername/db-mcp.git cd db-mcp ``` 2. Install dependencies ``` pip install -r requirements.txt ``` 3. Configure environment variables ``` cp config/example.env .env # Edit the .env file to set the database connection string and API key ``` ## Usage ### Server Mode Start the server mode, connect to the database, and provide MCP services: ```bash # Use the demo database (SQLite in-memory database) python main.py server --demo # Connect to MySQL database python main.py server --dsn "mysql://user:password@localhost:3306/dbname" # Connect to PostgreSQL database python main.py server --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable" # Connect to multiple databases simultaneously python main.py server --dsn "mysql://user:password@localhost:3306/dbname" --dsn "postgres://user:password@localhost:5432/dbname" --dsn "sqlite:///path/to/database.db" # Use SSE transport protocol (suitable for clients like Cursor) python main.py server --demo --transport sse --port 8080 # Specify AI provider python main.py server --demo --ai-provider deepseek --ai-api-key "your-api-key" ``` ### Client Mode Start the client mode, connect to the MCP server, and interact with the LLM: ```bash # Use default configuration (connect to demo server) python main.py client # Use configuration file python main.py client --config config/example.json # Specify LLM provider python main.py client --llm-provider deepseek --llm-api-key "your-api-key" ``` ## Database Connection String Formats The connection string formats for various databases are as follows: ### MySQL ``` mysql://user:password@localhost:3306/dbname ``` ### PostgreSQL ``` postgres://user:password@localhost:5432/dbname?sslmode=disable ``` ### SQLite ``` sqlite:///path/to/database.db sqlite::memory: # In-memory database ``` ### SQL Server ``` sqlserver://user:password@localhost:1433/dbname ``` ### MongoDB ``` mongodb://user:password@localhost:27017/dbname ``` ## Example Queries Once connected to the client, you can interact with the database using natural language: ``` User: List all tables AI: [List all tables in the database] User: What fields are in the employees table? AI: [Show the structure of the employees table] User: Query the top 3 employees with the highest salaries AI: [Execute the query and display the results] User: Generate an SQL query to find the average salary for each department AI: [Generate SQL and execute] # Multi-database scenario User: What tables are in the mysql_dbname database? AI: [List all tables in the MySQL database] User: Query the latest 10 registered users from the users table in the postgres_dbname database AI: [Execute PostgreSQL database query and display results] User: Find all products in the mongodb_database collection where the price is greater than 100 AI: [Execute MongoDB query and display results] User: Compare and analyze VIP customers from the mysql_dbname.customers table with order data from the sqlite_db.orders table AI: [Generate cross-database analysis results] ```