Custom MySQL MCP

A Model Context Protocol server that lets AI agents (Cursor, Claude Desktop, etc.) interact with a MySQL, PostgreSQL, or SQLite database — query data, inspect schemas, and optionally execute write operations. Comes with a persistent GUI (tabs, settings) accessible through the central proxy.

Tools

| Tool | Description | |---|---| | list_tables | List all tables in the connected database | | describe_table | Get the schema of a table (columns, types, keys, defaults) | | execute_query | Execute a read-only SELECT query and return results | | execute_write | Execute a write statement (INSERT, UPDATE, DELETE, ALTER…) — requires MYSQL_MCP_ALLOW_WRITE=true |

Configuration in Cursor

Add the following to your Cursor MCP configuration file (~/.cursor/mcp.json or your project's .cursor/mcp.json):

Via HTTP proxy (database-exposer)

Use this mode when you have a database-exposer instance deployed. No database credentials needed locally.

{
  "mcpServers": {
    "my-database": {
      "command": "npx",
      "args": ["-y", "custom-mysql-mcp"],
      "env": {
        "DB_PROXY_URL": "https://data.example.com",
        "DB_PROXY_TOKEN": "<your-query-token>"
      }
    }
  }
}

Via NPX (direct connection)

{
  "mcpServers": {
    "custom-mysql-mcp": {
      "command": "npx",
      "args": ["-y", "custom-mysql-mcp"],
      "env": {
        "MYSQL_MCP_HOST": "127.0.0.1",
        "MYSQL_MCP_PORT": "3306",
        "MYSQL_MCP_DATABASE": "my_database",
        "MYSQL_MCP_USERNAME": "my_user",
        "MYSQL_MCP_PASSWORD": "my_password",
        "MYSQL_MCP_ALLOW_WRITE": "false",
        "PROXY_URL": "http://localhost:4242",
        "CONFIG_PATH": "/path/to/persistent/config-dir"
      }
    }
  }
}

Via local install

{
  "mcpServers": {
    "custom-mysql-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/custom-mysql-mcp/dist/index.js"],
      "env": {
        "MYSQL_MCP_HOST": "127.0.0.1",
        "MYSQL_MCP_PORT": "3306",
        "MYSQL_MCP_DATABASE": "my_database",
        "MYSQL_MCP_USERNAME": "my_user",
        "MYSQL_MCP_PASSWORD": "my_password",
        "MYSQL_MCP_ALLOW_WRITE": "false",
        "PROXY_URL": "http://localhost:4242",
        "CONFIG_PATH": "/path/to/persistent/config-dir"
      }
    }
  }
}

Environment Variables

HTTP Proxy mode (database-exposer)

If DB_PROXY_URL and DB_PROXY_TOKEN are both set, the MCP routes all queries through an HTTP REST endpoint instead of connecting directly to the database. This mode is fully transparent to the agent — the same tools are available.

| Variable | Required | Description | |---|---|---| | DB_PROXY_URL | Yes† | Base URL of the database-exposer instance (e.g. https://data.example.com) | | DB_PROXY_TOKEN | Yes† | Bearer token for the database-exposer API |

† Both variables must be set together to activate proxy mode. If only one is present, the server falls back to direct connection mode.

Read-only: The database-exposer API only accepts SELECT, SHOW, DESCRIBE, and EXPLAIN queries. execute_write is automatically disabled in proxy mode.

Direct connection

| Variable | Required | Description | |---|---|---| | MYSQL_MCP_DB_TYPE | No | Database driver: mysql (default), postgres, or sqlite | | MYSQL_MCP_HOST | Yes* | Database server hostname or IP address | | MYSQL_MCP_PORT | Yes* | Database server port (3306 for MySQL, 5432 for Postgres) | | MYSQL_MCP_DATABASE | Yes* | Name of the database to connect to | | MYSQL_MCP_USERNAME | Yes* | Database username | | MYSQL_MCP_PASSWORD | Yes* | Database password | | MYSQL_MCP_SQLITE_PATH | Yes** | Path to the SQLite file (** required only when MYSQL_MCP_DB_TYPE=sqlite) | | MYSQL_MCP_ALLOW_WRITE | No | Set to true to enable write operations. Defaults to read-only. | | MYSQL_MCP_DEFAULT_MAX_ROWS | No | Maximum rows returned by MCP tools. Defaults to 10. | | MYSQL_MCP_DEFAULT_MAX_CELL_LENGTH | No | Max characters per cell before truncation. Defaults to 50. |

Security note: Write operations are disabled by default. You must explicitly set MYSQL_MCP_ALLOW_WRITE=true to allow INSERT, UPDATE, DELETE, and other write statements.

Result limits: By default, execute_query and execute_write return at most 10 rows, with cell values truncated at 50 characters. The response includes a meta.was_row_limited field to indicate when more results are available. These limits can be overridden per call via the max_rows and max_cell_length parameters, or globally via environment variables.

GUI & proxy

| Variable | Required | Description | |---|---|---| | PROXY_URL | No | URL of the central proxy. Required to enable the GUI (e.g. http://localhost:4242). | | PROXY_APP_PATH | No | Registration path in the proxy. Defaults to /mysql-mcp. | | PROXY_APP_NAME | No | Display name in the proxy dashboard. Defaults to MySQL MCP. | | CONFIG_PATH | No | Directory where the GUI config file (config.json) is stored. Can be absolute or relative to the project root. Defaults to <project root>/data/. | | MCP_LOG_DIR | No | Directory where log files are written. |

Config persistence: The GUI saves open tabs (name + SQL content) and general settings (max results) to config.json inside CONFIG_PATH. Reloading the page or restarting the server restores the exact state. Set CONFIG_PATH to a directory outside the MCP installation folder so data survives reinstalls and npx cache clears.

Development

# Install dependencies
npm install

# Run in development mode (no build required)
npm run dev

# Build for production
npm run build

# Start the compiled server
npm start

License

ISC