universal-db-mcp-connector

# Universal DB MCP Connector > Skill by [ara.so](https://ara.so) — MCP Skills collection. Universal DB MCP is a connector implementing the Model Context Protocol (MCP) that enables AI assistants to query and analyze databases using natural language. It supports 17 database types including MySQL, PostgreSQL, Oracle, MongoDB, Redis, and Chinese databases like Dameng, KingbaseES, and GaussDB. Works with 50+ platforms including Claude Desktop, Cursor, Windsurf, VS Code, ChatGPT, and Dify. ## Architecture Overview The connector operates in two modes: 1. **stdio mode** - Direct MCP protocol via stdio transport (for Claude Desktop, Cursor) 2. **http mode** - HTTP server exposing MCP via SSE/Streamable HTTP + REST API (for Dify, remote access) Both modes provide the same MCP tools for database operations. ## Installation ### Global Installation ```bash npm install -g universal-db-mcp ``` ### Project-Local Installation ```bash npm install universal-db-mcp ``` ### From Source ```bash git clone https://github.com/Anarkh-Lee/universal-db-mcp.git cd universal-db-mcp npm install npm run build ``` ## Supported Databases | Database | Type Value | Default Port | |----------|-----------|--------------| | MySQL | `mysql` | 3306 | | PostgreSQL | `postgres` | 5432 | | MongoDB | `mongodb` | 27017 | | Redis | `redis` | 6379 | | Oracle | `oracle` | 1521 | | SQL Server | `sqlserver` | 1433 | | SQLite | `sqlite` | N/A | | Dameng | `dm` | 5236 | | KingbaseES | `kingbase` | 54321 | | GaussDB | `gaussdb` | 5432 | | OceanBase | `oceanbase` | 2881 | | TiDB | `tidb` | 4000 | | ClickHouse | `clickhouse` | 8123 | | PolarDB | `polardb` | 3306 | | Vastbase | `vastbase` | 5432 | | HighGo | `highgo` | 5866 | | GoldenDB | `goldendb` | 3306 | ## Configuration for Claude Desktop ### macOS Edit `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "production-mysql": { "command": "npx", "args": [ "universal-db-mcp", "--type", "mysql", "--host", "localhost", "--port", "3306", "--user", "root", "--password", "${DB_PASSWORD}", "--database", "myapp", "--readonly" ] }, "analytics-postgres": { "command": "npx", "args": [ "universal-db-mcp", "--type", "postgres", "--host", "analytics.example.com", "--port", "5432", "--user", "analyst", "--password", "${ANALYTICS_DB_PASSWORD}", "--database", "analytics", "--schema", "public", "--cache-ttl", "600" ] }, "local-sqlite": { "command": "npx", "args": [ "universal-db-mcp", "--type", "sqlite", "--database", "/Users/me/data/app.db" ] } } } ``` ### Windows Edit `%APPDATA%\Claude\claude_desktop_config.json` with the same structure. ### Common CLI Arguments ```bash --type <database-type> # Required: mysql, postgres, mongodb, etc. --host <hostname> # Database host (default: localhost) --port <port> # Database port (uses default for type) --user <username> # Database user --password <password> # Database password (use env vars!) --database <db-name> # Database/schema name --schema <schema-name> # Schema name (PostgreSQL, SQL Server, Oracle) --readonly # Enable read-only mode (recommended) --cache-ttl <seconds> # Schema cache TTL (default: 300) --mask-sensitive-data # Enable automatic data masking --connection-timeout <ms> # Connection timeout (default: 10000) --pool-size <number> # Connection pool size (default: 10) ``` ## Configuration for Cursor / VS Code Edit `.cursor/config.json` or `.vscode/settings.json`: ```json { "mcp.servers": { "database": { "command": "npx", "args": [ "universal-db-mcp", "--type", "mysql", "--host", "localhost", "--user", "root", "--password", "${DB_PASSWORD}", "--database", "myapp" ] } } } ``` ## HTTP API Mode ### Starting the Server ```bash # Using environment variables export MODE=http export HTTP_PORT=3000 export API_KEYS=secret-key-1,secret-key-2 export ENABLE_CORS=true npx universal-db-mcp ``` Or with a config file: ```typescript // config.ts export default { mode: 'http', http: { port: 3000, apiKeys: ['secret-key-1', 'secret-key-2'], cors: true, rateLimit: { windowMs: 60000, maxRequests: 100 } } }; ``` ```bash npx universal-db-mcp --config config.ts ``` ### MCP over SSE (Legacy) Connect via Server-Sent Events: ```bash # Establish SSE connection curl -N "http://localhost:3000/sse?type=mysql&host=localhost&port=3306&user=root&password=mypass&database=mydb" \ -H "Authorization: Bearer secret-key-1" # Send MCP message curl -X POST http://localhost:3000/sse/message \ -H "Authorization: Bearer secret-key-1" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "execute_query", "arguments": { "query": "SELECT * FROM users LIMIT 10" } }, "id": 1 }' ``` ### MCP over Streamable HTTP (Recommended) ```bash # Execute query via MCP curl -X POST http://localhost:3000/mcp \ -H "Authorization: Bearer secret-key-1" \ -H "Content-Type: application/json" \ -H "X-DB-Type: mysql" \ -H "X-DB-Host: localhost" \ -H "X-DB-Port: 3306" \ -H "X-DB-User: root" \ -H "X-DB-Password: mypass" \ -H "X-DB-Database: mydb" \ -d '{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "execute_query", "arguments": { "query": "SELECT COUNT(*) as total FROM orders WHERE created_at >= DATE_SUB(NOW(), INTERVAL 7 DAY)" } }, "id": 1 }' ``` ### REST API Endpoints ```bash # Health check curl http://localhost:3000/api/health # Connect to database curl -X POST http://localhost:3000/api/connect \ -H "Authorization: Bearer secret-key-1" \ -H "Content-Type: application/json" \ -d '{ "type": "mysql", "host": "localhost", "port": 3306, "user": "root", "password": "mypass", "database": "mydb" }' # Execute query curl -X POST http://localhost:3000/api/query \ -H "Authorization: Bearer secret-key-1" \ -H "Content-Type: application/json" \ -d '{ "query": "SELECT * FROM products WHERE price > 100 ORDER BY price DESC LIMIT 10" }' # Get schema curl -X GET http://localhost:3000/api/schema \ -H "Authorization: Bearer secret-key-1" # Get table info curl -X POST http://localhost:3000/api/table \ -H "Authorization: Bearer secret-key-1" \ -H "Content-Type: application/json" \ -d '{ "tableName": "users" }' # Get sample data curl -X POST http://localhost:3000/api/sample \ -H "Authorization: Bearer secret-key-1" \ -H "Content-Type: application/json" \ -d '{ "tableName": "orders", "limit": 5 }' # Clear cache curl -X POST http://localhost:3000/api/cache/clear \ -H "Authorization: Bearer secret-key-1" # Get connection status curl -X GET http://localhost:3000/api/status \ -H "Authorization: Bearer secret-key-1" # Disconnect curl -X POST http://localhost:3000/api/disconnect \ -H "Authorization: Bearer secret-key-1" ``` ## MCP Tools Available ### execute_query Execute SQL queries (SELECT only in readonly mode). ```typescript // Request { "name": "execute_query", "arguments": { "query": "SELECT u.name, COUNT(o.id) as order_count FROM users u LEFT JOIN orders o ON u.id = o.user_id GROUP BY u.id HAVING order_count > 5" } } ``` ### get_schema Get complete database schema with table relationships. ```typescript // Request { "name": "get_schema", "arguments": {} } // Response includes: // - All tables with columns, types, constraints // - Primary keys, foreign keys // - Indexes, table comments // - Inferred relationships ``` ### get_table_info Get detailed information about a specific table. ```typescript { "name": "get_table_info", "arguments": { "tableName": "orders" } } ``` ### get_sample_data Get sample rows from a table. ```typescript { "name": "get_sample_data", "arguments": { "tableName": "products", "limit": 10 } } ``` ### get_enum_values Get all possible values for ENUM columns (MySQL). ```typescript { "name": "get_enum_values", "arguments": { "tableName": "users", "columnName": "status" } } ``` ### clear_cache Clear the schema cache to force refresh. ```typescript { "name": "clear_cache", "arguments": {} } ``` ### connect_database Dynamically connect to a different database. ```typescript { "name": "connect_database", "arguments": { "type": "postgres", "host": "analytics.example.com", "port": 5432, "user": "analyst", "password": "secure-password", "database": "analytics" } } ``` ### disconnect_database Disconnect from current database. ```typescript { "name": "disconnect_database", "arguments": {} } ```