mcp-mysql-long-connect

A Model Context Protocol (MCP) server for MySQL with long-lived connection keepalive.

This package is intended for MySQL environments where the database token remains valid for a short time after disconnect, and you want the MCP server to keep the database session warm so you do not have to repeatedly re-fetch username/password.

Features

• ✅ Long-lived MySQL connections
• ✅ Periodic keepalive ping/query to prevent token expiry
• ✅ Automatic reconnect when the database connection is lost
• ✅ Custom port support
• ✅ Timezone support
• ✅ BIGINT precision handling
• ✅ Query execution (SELECT)
• ✅ Data modification (INSERT, UPDATE, DELETE)
• ✅ List all tables
• ✅ Describe table structure

Installation

npx -y mcp-mysql-long-connect

Configuration

Windsurf / Cursor IDE

Add to your MCP configuration file:

Windsurf: ~/.codeium/windsurf/mcp_config.json

Cursor: ~/.cursor/mcp.json

Codex

If your Codex client uses a JSON MCP configuration block, you can use the following template:

{
  "mcpServers": {
    "mysql-long-connect": {
      "command": "npx",
      "args": ["-y", "mcp-mysql-long-connect"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database",
        "MYSQL_KEEPALIVE_INTERVAL_MS": "60000"
      }
    }
  }
}

Example

{
  "mcpServers": {
    "mysql-long-connect": {
      "command": "npx",
      "args": ["-y", "mcp-mysql-long-connect"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database",
        "MYSQL_KEEPALIVE_INTERVAL_MS": "240000"
      }
    }
  }
}

If you need to connect to multiple independent MySQL instances (different host / port / user / password), use MYSQL_INSTANCES:

Define the instances first:

[
  {
    "name": "order-db",
    "host": "10.0.0.10",
    "port": 3306,
    "user": "root",
    "password": "password-a",
    "databases": ["orders"],
    "enabled": true,
    "keepAliveIntervalMs": 60000
  },
  {
    "name": "user-db",
    "host": "10.0.0.11",
    "port": 3306,
    "user": "root",
    "password": "password-b",
    "databases": ["users", "profiles"],
    "enabled": false,
    "keepAliveIntervalMs": 120000
  }
]

Then place the stringified array into MYSQL_INSTANCES:

{
  "mcpServers": {
    "mysql-long-connect": {
      "command": "npx",
      "args": ["-y", "mcp-mysql-long-connect"],
      "env": {
        "MYSQL_INSTANCES": "[{\"name\":\"order-db\",\"host\":\"10.0.0.10\",\"port\":3306,\"user\":\"root\",\"password\":\"password-a\",\"databases\":[\"orders\"],\"enabled\":true,\"keepAliveIntervalMs\":60000},{\"name\":\"user-db\",\"host\":\"10.0.0.11\",\"port\":3306,\"user\":\"root\",\"password\":\"password-b\",\"databases\":[\"users\",\"profiles\"],\"enabled\":false,\"keepAliveIntervalMs\":120000}]"
      }
    }
  }
}

Tool names will be namespaced to avoid collisions:

• query_order-db
• execute_order-db
• query_user-db_users
• query_user-db_profiles

If you want to use only instance 1, set only its enabled to true and keep the others false. If you want to use instance 1 and 2, set both to true.

Per-instance fields supported inside MYSQL_INSTANCES:

• enabled
  • true to expose the instance and create its connections
  • false to keep it configured but inactive
• keepAliveIntervalMs
  • independent keepalive interval per instance
• keepAliveEnabled
  • independent keepalive on/off switch per instance
• keepAliveSql
  • optional keepalive SQL per instance

If your database is a single MySQL instance with multiple databases, you can still use:

{
  "env": {
    "MYSQL_HOST": "localhost",
    "MYSQL_PORT": "3306",
    "MYSQL_USER": "root",
    "MYSQL_PASSWORD": "your_password",
    "MYSQL_DATABASES": "clx_performance,purchase_manage"
  }
}

When multiple databases are configured, tools will be generated with database suffixes:

• query_clx_performance, query_purchase_manage
• execute_clx_performance, execute_purchase_manage
• list_tables_clx_performance, list_tables_purchase_manage
• describe_table_clx_performance, describe_table_purchase_manage

When MYSQL_INSTANCES is used, the tool suffix format becomes:

• query_<instance> for a single database in that instance
• query_<instance>_<database> when an instance exposes multiple databases
• Same pattern applies to execute, list_tables, and describe_table

Environment Variables

Variable	Description	Default
MYSQL_INSTANCES	JSON array of independent MySQL instance configs	(empty)
MYSQL_HOST	MySQL server hostname	localhost
MYSQL_PORT	MySQL server port	3306
MYSQL_USER	MySQL username	root
MYSQL_PASSWORD	MySQL password	(empty)
MYSQL_DATABASE	Single database name	(empty)
MYSQL_DATABASES	Multiple database names, comma-separated	(empty)
MYSQL_TIMEZONE	Timezone for datetime fields	+08:00
ALLOW_DDL	Allow DDL operations	false
ALLOW_DML	Allow DML operations	false
MYSQL_KEEPALIVE	Enable/disable keepalive loop	true
MYSQL_KEEPALIVE_INTERVAL_MS	Keepalive interval in milliseconds	240000
MYSQL_KEEPALIVE_SQL	SQL used for keepalive probing	SELECT 1

Keepalive Strategy

This server keeps the MySQL connection open and sends a lightweight keepalive query on a timer.

Recommended settings for token-based authentication:

• Keep the interval below the token expiration window.
• If the token becomes invalid 5 minutes after disconnect, use 240000 ms or lower.
• Leave the MCP server process running continuously.

Permission Control

By default, this MCP server runs in read-only mode. DDL and DML operations are disabled for safety.

To enable write operations, set the corresponding environment variables:

{
  "env": {
    "MYSQL_HOST": "localhost",
    "MYSQL_PORT": "3306",
    "MYSQL_USER": "root",
    "MYSQL_PASSWORD": "your_password",
    "MYSQL_DATABASE": "your_database",
    "ALLOW_DML": "true",
    "ALLOW_DDL": "true"
  }
}

Available Tools

query

Execute a SELECT query on the MySQL database.

SELECT * FROM users LIMIT 10

execute

Execute INSERT, UPDATE, or DELETE queries.

INSERT INTO users (name, email) VALUES ('John', 'john@example.com')

list_tables

List all tables in the current database.

describe_table

Get the structure of a specific table.

Notes

• This package is optimized for persistent MCP server sessions.
• It is not meant for short-lived one-shot database access.
• If the MCP host fully terminates the process, the database connection will still be closed.

License

MIT