README.md
Natural language interface for querying and managing SQL databases
Database MCP - Natural Language Database Interface
A modern web application that lets you interact with SQL databases using natural language, powered by the Model Context Protocol (MCP).
Features
- Natural Language Queries: Ask questions in plain English, get results instantly
- Multi-Database Support: PostgreSQL, MySQL, MariaDB, MSSQL, SQLite
- Rich Visualizations: Tables, charts, and formatted code blocks
- Schema Explorer: Browse database structure with an intuitive sidebar
- Dark & Light Modes: Modern design with light/dark theme support
- Responsive Design: Works on desktop, tablet, and mobile
Prerequisites
- Node.js 18+
- A database (PostgreSQL, MySQL, MSSQL, or SQLite)
- LLM API key (Groq, OpenAI, or compatible endpoint)
Setup & Installation
1. Install Dependencies
npm install
2. Configure Environment
Copy .env.example to .env and update with your credentials:
cp .env.example .env
Then edit .env with:
LLM_API_URL: Your LLM API endpoint (e.g., Groq, OpenAI)LLM_API_KEY: Your API keyLLM_MODEL: Model name (e.g., mixtral-8x7b-32768)ENCRYPTION_KEY: A 32-character random key for production
3. Run Development Server
npm run dev
The application will start at http://localhost:3000
Available Scripts
npm run dev # Development with hot reload
npm run build # Build TypeScript
npm start # Run production build
npm run demo:setup # Create demo database
npm run demo:run # Run with demo data
npm test # Run tests
Supported Databases
| Database | Status |
|---|---|
| PostgreSQL | ✅ |
| MySQL / MariaDB | ✅ |
| SQL Server | ✅ |
| SQLite | ✅ |
Architecture
Web UI → Chat → MCP Tools → Scanner → Database
Key Components:
- Frontend (
public/): Interactive UI with theme support - Server (
src/server.ts): Express API and MCP - Tools (
src/mcp/): MCP protocol implementation - Providers (
src/providers/): Database adapters - Scanner (
src/scanner/): Database schema analysis - Encryption (
src/utils/encryption.ts): Credential encryption
License
MIT
Environment Variables
LLM_API_URLrequiredYour LLM API endpoint (e.g., Groq, OpenAI)LLM_API_KEYrequiredYour API keyLLM_MODELrequiredModel name (e.g., mixtral-8x7b-32768)ENCRYPTION_KEYrequiredA 32-character random key for productionConfiguration
claude_desktop_config.json
{
"mcpServers": {
"database-mcp": {
"command": "npm",
"args": ["start"],
"env": {
"LLM_API_URL": "your-api-url",
"LLM_API_KEY": "your-api-key",
"LLM_MODEL": "mixtral-8x7b-32768"
}
}
}
}Try it
→Show me the schema for my PostgreSQL database.
→Find the top 10 customers by total order value in my MySQL database.
→Create a chart showing monthly revenue growth from the SQLite database.
→List all tables in my MSSQL database and explain their relationships.