MySQL MCP Server

MCP server for MySQL 8.0 with connection pooling and parameterized queries.

Features

• Execute SQL queries with parameterized placeholders
• List databases and tables
• Describe table structures
• Connection pooling for performance

Prerequisites

• Node.js >=25.2.1
• MySQL 8.0+

Installation

Option 1: Use with npx (Recommended - no installation needed)

npx -y @teolin/mcp-local-mysql

Option 2: Install from npm globally

npm install -g @teolin/mcp-local-mysql

Option 3: Install locally

npm install @teolin/mcp-local-mysql

Setup

1. Configure .env:

cp .env.example .env
# Edit .env with your MySQL credentials

Required environment variables:

• MYSQL_HOST - MySQL host (e.g., localhost)
• MYSQL_PORT - MySQL port (e.g., 3306)
• MYSQL_USER - MySQL username
• MYSQL_PASSWORD - MySQL password
• MYSQL_DATABASE - Default database name

Usage

Running as a standalone server

# If installed globally
mysql-mcp

# If installed locally or using npx
npx @teolin/mcp-local-mysql

# Or using npm start (for development)
npm start

Running tests

npm test

Available Tools

• query - Execute SQL queries (supports parameterized queries with ? placeholders)
• list_databases - List all databases
• list_tables - List tables in a database
• describe_table - Show table structure

Integration with Claude Code

Claude Code supports three scopes for MCP server configuration:

• User scope (~/.claude.json): Available across all projects
• Local scope (~/.claude.json): Project-specific, private to you (default)
• Project scope (.mcp.json in project root): Team-shared, committed to git

Quick Setup with CLI (Recommended)

# User scope (available in all projects)
claude mcp add mysql --scope user

# Project scope (shared with team via git)
claude mcp add mysql --scope project

Manual Configuration

Using npx (Recommended - no installation needed)

Add to .mcp.json (project scope) or ~/.claude.json (user scope):

{
  "mcpServers": {
    "mysql": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@teolin/mcp-local-mysql"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Using global installation

{
  "mcpServers": {
    "mysql": {
      "type": "stdio",
      "command": "mysql-mcp",
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Using local installation

{
  "mcpServers": {
    "mysql": {
      "type": "stdio",
      "command": "node",
      "args": [
        "./node_modules/@teolin/mcp-local-mysql/src/index.js"
      ],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Publishing

Using GitHub Actions (Recommended)

This package uses GitHub Actions for automated publishing. To publish a new version:

1. Go to GitHub Actions → "Publish @teolin/mcp-local-mysql" → Run workflow
2. The workflow will automatically:
   • Install dependencies
   • Run the prepublishOnly script to make the bin executable
   • Publish to npm with public access

Manual Publishing

Prerequisites

1. You need an npm account: https://www.npmjs.com/signup
2. Login to npm:

   npm login

Publishing Steps

1. Test the package locally (optional but recommended):

   # Test that it runs
   node src/index.js --help
   
   # Or test with environment variables
   MYSQL_HOST=localhost MYSQL_PORT=3306 MYSQL_USER=root MYSQL_PASSWORD=password MYSQL_DATABASE=test node src/index.js

2. Publish to npm:

   npm publish

   This will:

   • Run the prepublishOnly script to make the bin executable
   • Only include files specified in the files field
   • Publish to npm with public access (configured in publishConfig)

3. Verify the package:

   # Test with npx (no installation)
   npx -y @teolin/mcp-local-mysql
   
   # Or install globally and test
   npm install -g @teolin/mcp-local-mysql
   mysql-mcp

Updating the Package

1. Update the version in package.json:

   npm version patch  # for bug fixes (2.0.2 -> 2.0.3)
   npm version minor  # for new features (2.0.2 -> 2.1.0)
   npm version major  # for breaking changes (2.0.2 -> 3.0.0)

2. Publish the new version:

   npm publish

Checking Published Package

View your package on npm:

• https://www.npmjs.com/package/@teolin/mcp-local-mysql

Check what files will be included before publishing:

npm pack --dry-run

Troubleshooting

"You do not have permission to publish"

• Make sure you're logged in: npm whoami
• For scoped packages (@teolin/...), ensure you have access to the @teolin organization or use your own scope

"Package name already exists"

• The package name might be taken. Check: https://www.npmjs.com/package/@teolin/mcp-local-mysql
• If needed, change the name in package.json

Files missing after installation

• Check the files field in package.json
• Use npm pack --dry-run to preview what will be included

Requirements

• Node.js >=25.2.1
• MySQL 8.0+
• Published on npm: @teolin/mcp-local-mysql

License

MIT