MCP SQL Server
A Model Context Protocol (MCP) server for querying PostgreSQL and MySQL databases.
Quick Start
Recommended: Use npx to run without installation:
npx postgres-mysql-mcp-server
For MCP client configuration (Cursor, Windsurf, etc.), use:
{
"mcpServers": {
"sql": {
"command": "npx",
"args": ["-y", "postgres-mysql-mcp-server"],
"env": {
"DB_TYPE": "postgresql",
"DB_HOST": "localhost",
"DB_PORT": "5432",
"DB_DATABASE": "mydb",
"DB_USER": "postgres",
"DB_PASSWORD": "password"
}
}
}
}
What is MCP and Why Use It?
Model Context Protocol (MCP) is a standardized protocol that enables AI assistants in code editors like Cursor, Windsurf, and other AI-powered development tools to securely interact with external systems and data sources.
This MCP server bridges the gap between your AI coding assistant and your databases, allowing the AI to:
- Understand your database schema - The AI can explore tables, columns, and relationships
- Write accurate SQL queries - Generate queries based on your actual database structure
- Debug database issues - Query data to understand problems and verify fixes
- Generate database-aware code - Create application code that matches your database schema
- Answer questions about your data - Query the database to provide accurate information
Perfect for AI-Powered Editors
When integrated with AI editors like Cursor or Windsurf, this MCP server transforms your AI assistant into a database-aware coding companion:
Example Use Cases:
-
Schema-Aware Code Generation
- You: "Create a user registration API endpoint"
- AI: Automatically queries your database schema, understands the
userstable structure, and generates code that matches your exact column names and types
-
Intelligent Query Writing
- You: "Show me all active users from the last 30 days"
- AI: Connects to your database, checks the schema, and writes a correct SQL query using your actual table and column names
-
Database Debugging
- You: "Why is my user login failing?"
- AI: Queries your database to check user records, verify table structures, and identify potential issues
-
Data-Driven Development
- You: "Create a dashboard showing user statistics"
- AI: Explores your database schema, understands relationships, and generates accurate queries and code
-
Migration and Refactoring
- You: "Refactor this code to use the new database schema"
- AI: Compares your code with the actual database schema and suggests accurate changes
How It Works
- Configure the MCP server in your AI editor (Cursor, Windsurf, etc.)
- Connect to your PostgreSQL or MySQL database
- Ask your AI assistant questions or request code generation
- AI uses the MCP server to query your database schema and data
- Get accurate, database-aware responses and code
The AI assistant can now "see" your database structure and data, making it much more helpful and accurate in generating database-related code.
Features
- Connect to PostgreSQL and MySQL databases
- Execute SQL queries
- List database tables
- Describe table schemas
- Parameterized query support
- Connection pooling for better performance
- Secure credential management via environment variables
- Auto-connect on startup when environment variables are set
Installation
Option 1: Use with npx (Recommended - No installation required)
Recommended: Run the server directly with npx without any installation. This is the simplest and most convenient method:
npx postgres-mysql-mcp-server
The -y flag is automatically handled by npx, so it will download and run the latest version without prompts.
Option 2: Install via npm
If you prefer to install the package:
Global installation:
npm install -g postgres-mysql-mcp-server
Local installation in your project:
npm install postgres-mysql-mcp-server
Option 3: Development Installation
For local development or contributing:
git clone https://github.com/TranChiHuu/postgres-mysql-mcp-server.git
cd postgres-mysql-mcp-server
npm install
Usage
Running the Server
The server runs on stdio and communicates via the MCP protocol.
Recommended: Using npx (no installation required)
npx postgres-mysql-mcp-server
This is the recommended way to run the server. npx will automatically download and run the latest version.
Alternative: Using globally installed package
postgres-mysql-mcp-server
For local development:
npm start
Available Tools
1. connect_database
Connect to a PostgreSQL or MySQL database. Parameters can be provided directly, loaded from environment variables, or a combination of both. If environment variables are set, the server will auto-connect on startup.
Parameters (all optional if using environment variables):
type(string, optional): Database type - "postgresql" or "mysql"host(string, optional): Database hostport(number, optional): Database portdatabase(string, optional): Database nameuser(string, optional): Database userpassword(string, optional): Database passwordssl(boolean, optional): Use SSL connection (default: false)
Examples:
Using parameters:
{
"type": "postgresql",
"host": "localhost",
"port": 5432,
"database": "mydb",
"user": "postgres",
"password": "password"
}
Using environment variables (call without parameters):
{}
Mixing parameters with environment variables:
{
"type": "postgresql",
"host": "custom-host"
}
2. execute_query
Execute a SQL query on the connected database.
Parameters:
query(string, required): SQL query to executeparams(array, optional): Query parameters for parameterized queries
Example:
{
"query": "SELECT * FROM users WHERE id = $1",
"params": [123]
}
3. list_tables
List all tables in the connected database.
Parameters: None
4. describe_table
Get schema information for a specific table.
Parameters:
tableName(string, required): Name of the table to describe
Example:
{
"tableName": "users"
}
5. disconnect_database
Disconnect from the current database.
Parameters: None
Configuration
Environment Variables
You can configure database connection using environment variables. Create a .env file in the project root or set environment variables:
Option 1: Generic Environment Variables (works for both PostgreSQL and MySQL)
DB_TYPE=postgresql # or "mysql"
DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=mydb
DB_USER=postgres
DB_PASSWORD=password
DB_SSL=false # optional, set to "true" for SSL
Option 2: PostgreSQL-Specific Environment Variables
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DATABASE=mydb
POSTGRES_USER=postgres
POSTGRES_PASSWORD=password
POSTGRES_SSL=false # optional
Option 3: MySQL-Specific Environment Variables
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_DATABASE=mydb
MYSQL_USER=root
MYSQL_PASSWORD=password
MYSQL_SSL=false # optional
Note: If environment variables are set, the server will automatically connect on startup. You can also call connect_database without parameters to use environment variables, or provide partial parameters that will be merged with environment variables.
MCP Client Configuration
This MCP server integrates seamlessly with AI-powered code editors. Add it to your MCP client configuration to enable database-aware AI assistance.
Supported Editors
- Cursor - AI-powered code editor
- Windsurf - AI-first IDE
- Any editor that supports the Model Context Protocol
Configuration Steps
For Cursor:
- Open Cursor Settings
- Navigate to Features → Model Context Protocol
- Add the server configuration below
For Windsurf:
- Open Settings
- Navigate to MCP Servers
- Add the server configuration below
For other MCP-compatible editors:
Add the configuration to your MCP settings file (typically ~/.config/mcp/settings.json or editor-specific location)
Configuration Options
Option 1: Using npx (Recommended - No installation required)
This is the recommended configuration. npx automatically downloads and runs the latest version without requiring any installation:
{
"mcpServers": {
"sql": {
"command": "npx",
"args": ["-y", "postgres-mysql-mcp-server"],
"env": {
"DB_TYPE": "postgresql",
"DB_HOST": "localhost",
"DB_PORT": "5432",
"DB_DATABASE": "mydb",
"DB_USER": "postgres",
"DB_PASSWORD": "password"
}
}
}
}
Benefits of using npx:
- ✅ No installation required
- ✅ Always uses the latest version
- ✅ No manual updates needed
- ✅ Works across different projects without conflicts
- ✅ The
-yflag automatically answers "yes" to install prompts
Option 2: Using globally installed package
If you've installed the package globally (npm install -g postgres-mysql-mcp-server):
{
"mcpServers": {
"sql": {
"command": "postgres-mysql-mcp-server",
"env": {
"DB_TYPE": "postgresql",
"DB_HOST": "localhost",
"DB_PORT": "5432",
"DB_DATABASE": "mydb",
"DB_USER": "postgres",
"DB_PASSWORD": "password"
}
}
}
}
Option 3: Using local installation
If you've installed the package locally in your project (npm install postgres-mysql-mcp-server):
{
"mcpServers": {
"sql": {
"command": "node",
"args": ["./node_modules/postgres-mysql-mcp-server/index.js"],
"env": {
"DB_TYPE": "postgresql",
"DB_HOST": "localhost",
"DB_PORT": "5432",
"DB_DATABASE": "mydb",
"DB_USER": "postgres",
"DB_PASSWORD": "password"
}
}
}
}
Option 4: Development setup (for local development)
If you're developing locally and have cloned the repository:
{
"mcpServers": {
"sql": {
"command": "npm",
"args": ["start"],
"cwd": "/path-to-source/postgres-mysql-mcp-server",
"env": {
"DB_TYPE": "postgresql",
"DB_HOST": "localhost",
"DB_PORT": "5432",
"DB_DATABASE": "mydb",
"DB_USER": "postgres",
"DB_PASSWORD": "password"
}
}
}
}
Example: Using with Cursor AI
Once configured, you can interact with your database through natural language:
Example Conversation:
You: "What tables are in my database?"
AI: [Uses list_tables tool] "Your database contains: users, orders, products, categories"
You: "Show me the structure of the users table"
AI: [Uses describe_table tool] "The users table has: id (integer), email (varchar), created_at (timestamp)..."
You: "Create an API endpoint to get user by ID"
AI: [Uses describe_table to understand schema, then generates code]
"Here's the endpoint matching your users table structure..."
The AI assistant automatically uses the appropriate MCP tools to query your database and provide accurate, schema-aware responses.
Development
The project uses plain JavaScript (ES modules), so no build step is required. Just edit index.js and run npm start.
Security Notes
- Never commit database credentials to version control
- Use environment variables or secure credential management
- The server supports SSL connections for secure database access
- Always validate and sanitize SQL queries in production environments
Requirements
- Node.js 18+
- PostgreSQL or MySQL database access
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
MIT