SQL MCP Gateway (NestJS)

NestJS-based MCP server for MySQL with session-level database selection and SQL safety controls.

Features

• MCP tools:
  • list_databases
  • connect_mysql_user
  • select_database
  • execute_sql
• Two transports:
  • HTTP (/mcp) via streamable HTTP sessions
  • stdio (--stdio) for command-based MCP auto-start
• SQL controls:
  • SQL_MODE: SAFE | WRITE | FULL
  • mode categories:
    • SAFE => DQL
    • WRITE => DQL, DML
    • FULL => DQL, DML, DDL, TCL, DCL
  • hard block on destructive statements like DROP, TRUNCATE, ALTER DATABASE/SCHEMA, RENAME TABLE

Project Structure

src/
  main.ts
  app.module.ts
  config/
  sql/
  mcp/
scripts/
  run-stdio.sh

Setup

npm install
cp .env.example .env

.env.example:

MCP_HOST=0.0.0.0
MCP_PORT=8787
MCP_PATH=/mcp
MCP_SERVER_NAME=sql-mcp
MCP_SERVER_VERSION=2.0.0
DATABASE_HOST=127.0.0.1
DATABASE_PORT=3306
SQL_MODE=SAFE

Run

HTTP mode (manual)

npm start

Endpoint: http://localhost:8787/mcp

stdio mode (auto-start via command MCP)

Build once:

npm run build

Then run:

scripts/run-stdio.sh

Or:

node build/main.js --stdio

MCP_TRANSPORT=stdio also enables stdio mode.

Cursor Config (~/.cursor/mcp.json)

Recommended: command mode (auto-start)

{
  "mcpServers": {
    "sql-mcp": {
      "command": "/ABSOLUTE/PATH/TO/sql-mcp/scripts/run-stdio.sh",
      "env": {
        "MCP_SQL_USER": "your_mysql_user",
        "MCP_SQL_PASSWORD": "your_mysql_password"
      }
    }
  }
}

Notes:

• Replace /ABSOLUTE/PATH/TO/sql-mcp with your actual repo path.
• MCP_SQL_USER / MCP_SQL_PASSWORD are optional. If omitted, use connect_mysql_user from chat.

Alternative: URL mode (manual server)

{
  "mcpServers": {
    "sql-mcp": {
      "url": "http://localhost:8787/mcp",
      "headers": {
        "x-sql-user": "your_mysql_user",
        "x-sql-password": "your_mysql_password"
      }
    }
  }
}

Use this only when the HTTP server is running.

Tool Workflow

If credentials are preconfigured (command env or URL headers)

1. list_databases
2. select_database
3. execute_sql

If credentials are not preconfigured

1. connect_mysql_user
2. select_database
3. execute_sql

Security

• Keep credentials only in user-level ~/.cursor/mcp.json.
• Do not commit project-level .cursor/mcp.json.