MCP Server for MySQL - Claude Code Edition

1# MCP Server for MySQL - Claude Code Edition
2 
3> **🚀 This is a modified version optimized for Claude Code with SSH tunnel support**  
4> **Original Author:** [@benborla29](https://github.com/benborla)  
5> **Original Repository:** [https://github.com/benborla/mcp-server-mysql](https://github.com/benborla/mcp-server-mysql)  
6> **License:** MIT  
7 
8## MCP Server for MySQL based on NodeJS
9 
10[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/benborla/mcp-server-mysql)](https://archestra.ai/mcp-catalog/benborla__mcp-server-mysql)
11 
12### Key Features of This Fork
13 
14- ✅ **Claude Code Integration** - Optimized for use with Anthropic's Claude Code CLI
15- ✅ **SSH Tunnel Support** - Built-in support for SSH tunnels to remote databases
16- ✅ **Auto-start/stop Hooks** - Automatic tunnel management with Claude start/stop
17- ✅ **DDL Operations** - Added `MYSQL_DISABLE_READ_ONLY_TRANSACTIONS` for CREATE TABLE support
18- ✅ **Multi-Project Setup** - Easy configuration for multiple projects with different databases
19 
20### Quick Start for Claude Code Users
21 
221. **Read the Setup Guide**: See [PROJECT_SETUP_GUIDE.md](PROJECT_SETUP_GUIDE.md) for detailed instructions
232. **Configure SSH Tunnels**: Set up automatic SSH tunnels for remote databases
243. **Use with Claude**: Integrated MCP server works seamlessly with Claude Code
25 
26A Model Context Protocol server that provides access to MySQL databases through SSH tunnels. This server enables Claude and other LLMs to inspect database schemas and execute SQL queries securely.
27 
28## Table of Contents
29 
30- [Requirements](#requirements)
31- [Installation](#installation)
32  - [Smithery](#using-smithery)
33  - [Clone to Local Repository](#running-from-local-repository)
34  - [Remote mode](#run-in-remote-mode)
35- [Components](#components)
36- [Configuration](#configuration)
37- [Environment Variables](#environment-variables)
38- [Multi-DB Mode](#multi-db-mode)
39- [Schema-Specific Permissions](#schema-specific-permissions)
40- [Testing](#testing)
41- [Troubleshooting](#troubleshooting)
42- [Contributing](#contributing)
43- [License](#license)
44 
45## Requirements
46 
47- Node.js v20 or higher
48- MySQL 5.7 or higher (MySQL 8.0+ recommended)
49- MySQL user with appropriate permissions for the operations you need
50- For write operations: MySQL user with INSERT, UPDATE, and/or DELETE privileges
51 
52## Installation
53 
54### Using Smithery
55 
56There are several ways to install and configure the MCP server but the most common would be checking this website [https://smithery.ai/server/@benborla29/mcp-server-mysql](https://smithery.ai/server/@benborla29/mcp-server-mysql)
57 
58### Cursor
59 
60For Cursor IDE, you can install this MCP server with the following command in your project:
61 
621. Visit [https://smithery.ai/server/@benborla29/mcp-server-mysql](https://smithery.ai/server/@benborla29/mcp-server-mysql)
632. Follow the instruction for Cursor
64 
65MCP Get provides a centralized registry of MCP servers and simplifies the installation process.
66 
67### Codex CLI
68 
69Codex CLI installation is similar to Claude Code below
70 
71```bash
72codex mcp add mcp_server_mysql \
73  --env MYSQL_HOST="127.0.0.1" \
74  --env MYSQL_PORT="3306" \
75  --env MYSQL_USER="root" \
76  --env MYSQL_PASS="your_password" \
77  --env MYSQL_DB="your_database" \
78  --env ALLOW_INSERT_OPERATION="false" \
79  --env ALLOW_UPDATE_OPERATION="false" \
80  --env ALLOW_DELETE_OPERATION="false" \
81  -- npx -y @benborla29/mcp-server-mysql
82```
83 
84### Claude Code
85 
86#### Option 1: Import from Claude Desktop (Recommended if already configured)
87 
88If you already have this MCP server configured in Claude Desktop, you can import it automatically:
89 
90```bash
91claude mcp add-from-claude-desktop
92```
93 
94This will show an interactive dialog where you can select your `mcp_server_mysql` server to import with all existing configuration.
95 
96#### Option 2: Manual Configuration
97 
98**Using NPM/PNPM Global Installation:**
99 
100First, install the package globally:
101 
102```bash
103# Using npm
104npm install -g @benborla29/mcp-server-mysql
105 
106# Using pnpm
107pnpm add -g @benborla29/mcp-server-mysql
108```
109 
110Then add the server to Claude Code:
111 
112```bash
113claude mcp add mcp_server_mysql \
114  -e MYSQL_HOST="127.0.0.1" \
115  -e MYSQL_PORT="3306" \
116  -e MYSQL_USER="root" \
117  -e MYSQL_PASS="your_password" \
118  -e MYSQL_DB="your_database" \
119  -e ALLOW_INSERT_OPERATION="false" \
120  -e ALLOW_UPDATE_OPERATION="false" \
121  -e ALLOW_DELETE_OPERATION="false" \
122  -- npx @benborla29/mcp-server-mysql
123```
124 
125**Using Local Repository (for development):**
126 
127If you're running from a cloned repository:
128 
129```bash
130claude mcp add mcp_server_mysql \
131  -e MYSQL_HOST="127.0.0.1" \
132  -e MYSQL_PORT="3306" \
133  -e MYSQL_USER="root" \
134  -e MYSQL_PASS="your_password" \
135  -e MYSQL_DB="your_database" \
136  -e ALLOW_INSERT_OPERATION="false" \
137  -e ALLOW_UPDATE_OPERATION="false" \
138  -e ALLOW_DELETE_OPERATION="false" \
139  -e PATH="/path/to/node/bin:/usr/bin:/bin" \
140  -e NODE_PATH="/path/to/node/lib/node_modules" \
141  -- /path/to/node /full/path/to/mcp-server-mysql/dist/index.js
142```
143 
144Replace:
145 
146- `/path/to/node` with your Node.js binary path (find with `which node`)
147- `/full/path/to/mcp-server-mysql` with the full path to your cloned repository
148- Update MySQL credentials to match your environment
149 
150**Using Unix Socket Connection:**
151 
152For local MySQL instances using Unix sockets:
153 
154```bash
155claude mcp add mcp_server_mysql \
156  -e MYSQL_SOCKET_PATH="/tmp/mysql.sock" \
157  -e MYSQL_USER="root" \
158  -e MYSQL_PASS="your_password" \
159  -e MYSQL_DB="your_database" \
160  -e ALLOW_INSERT_OPERATION="false" \
161  -e ALLOW_UPDATE_OPERATION="false" \
162  -e ALLOW_DELETE_OPERATION="false" \
163  -- npx @benborla29/mcp-server-mysql
164```
165 
166#### Choosing the Right Scope
167 
168Consider which scope to use based on your needs:
169 
170```bash
171# Local scope (default) - only available in current project
172claude mcp add mcp_server_mysql [options...]
173 
174# User scope - available across all your projects
175claude mcp add mcp_server_mysql -s user [options...]
176 
177# Project scope - shared with team members via .mcp.json
178claude mcp add mcp_server_mysql -s project [options...]
179```
180 
181For database servers with credentials, **local** or **user** scope is recommended to keep credentials private.
182 
183#### Verification
184 
185After adding the server, verify it's configured correctly:
186 
187```bash
188# List all configured servers
189claude mcp list
190 
191# Get details for your MySQL server
192claude mcp get mcp_server_mysql
193 
194# Check server status within Claude Code
195/mcp
196```
197 
198#### Multi-Database Configuration
199 
200For multi-database mode, omit the `MYSQL_DB` environment variable:
201 
202```bash
203claude mcp add mcp_server_mysql_multi \
204  -e MYSQL_HOST="127.0.0.1" \
205  -e MYSQL_PORT="3306" \
206  -e MYSQL_USER="root" \
207  -e MYSQL_PASS="your_password" \
208  -e MULTI_DB_WRITE_MODE="false" \
209  -- npx @benborla29/mcp-server-mysql
210```
211 
212#### Advanced Configuration
213 
214For advanced features, add additional environment variables:
215 
216```bash
217claude mcp add mcp_server_mysql \
218  -e MYSQL_HOST="127.0.0.1" \
219  -e MYSQL_PORT="3306" \
220  -e MYSQL_USER="root" \
221  -e MYSQL_PASS="your_password" \
222  -e MYSQL_DB="your_database" \
223  -e MYSQL_POOL_SIZE="10" \
224  -e MYSQL_QUERY_TIMEOUT="30000" \
225  -e MYSQL_CACHE_TTL="60000" \
226  -e MYSQL_RATE_LIMIT="100" \
227  -e MYSQL_SSL="true" \
228  -e ALLOW_INSERT_OPERATION="false" \
229  -e ALLOW_UPDATE_OPERATION="false" \
230  -e ALLOW_DELETE_OPERATION="false" \
231  -e MYSQL_ENABLE_LOGGING="true" \
232  -- npx @benborla29/mcp-server-mysql
233```
234 
235#### Troubleshooting Claude Code Setup
236 
2371. **Server Connection Issues**: Use `/mcp` command in Claude Code to check server status and authenticate if needed.
238 
2392. **Path Issues**: If using a local repository, ensure Node.js paths are correctly set:
240 
241   ```bash
242   # Find your Node.js path
243   which node
244 
245   # For PATH environment variable
246   echo "$(which node)/../"
247 
248   # For NODE_PATH environment variable
249   echo "$(which node)/../../lib/node_modules"
250   ```
251 
2523. **Permission Errors**: Ensure your MySQL user has appropriate permissions for the operations you've enabled.
253 
2544. **Server Not Starting**: Check Claude Code logs or run the server directly to debug:
255 
256   ```bash
257   # Test the server directly
258   npx @benborla29/mcp-server-mysql
259   ```
260 
261### Using NPM/PNPM
262 
263For manual installation:
264 
265```bash
266# Using npm
267npm install -g @benborla29/mcp-server-mysql
268 
269# Using pnpm
270pnpm add -g @benborla29/mcp-server-mysql
271```
272 
273After manual installation, you'll need to configure your LLM application to use the MCP server (see Configuration section below).
274 
275### Running from Local Repository
276 
277If you want to clone and run this MCP server directly from the source code, follow these steps:
278 
2791. **Clone the repository**
280 
281   ```bash
282   git clone https://github.com/benborla/mcp-server-mysql.git
283   cd mcp-server-mysql
284   ```
285 
2862. **Install dependencies**
287 
288   ```bash
289   npm install
290   # or
291   pnpm install
292   ```
293 
2943. **Build the project**
295 
296   ```bash
297   npm run build
298   # or
299   pnpm run build
300   ```
301 
3024. **Configure Claude Desktop**
303 
304   Add the following to your Claude Desktop configuration file (`claude_desktop_config.json`):
305 
306   ```json
307   {
308     "mcpServers": {
309       "mcp_server_mysql": {
310         "command": "/path/to/node",
311         "args": [
312           "/full/path/to/mcp-server-mysql/dist/index.js"
313         ],
314         "env": {
315           "MYSQL_HOST": "127.0.0.1",
316           "MYSQL_PORT": "3306",
317           "MYSQL_USER": "root",
318           "MYSQL_PASS": "your_password",
319           "MYSQL_DB": "your_database",
320           "ALLOW_INSERT_OPERATION": "false",
321           "ALLOW_UPDATE_OPERATION": "false",
322           "ALLOW_DELETE_OPERATION": "false",
323           "PATH": "/path/to/node/bin:/usr/bin:/bin", // <--- Important to add the following, run in your terminal `echo "$(which node)/../"` to get the path
324           "NODE_PATH": "/path/to/node/lib/node_modules" // <--- Important to add the following, run in your terminal `echo "$(which node)/../../lib/node_modules"`
325         }
326       }
327     }
328   }
329   ```
330 
331   Replace:
332   - `/path/to/node` with the full path to your Node.js binary (find it with `which node`)
333   - `/full/path/to/mcp-server-mysql` with the full path to where you cloned the repository
334   - Set the MySQL credentials to match your environment
335 
3365. **Test the server**
337 
338   ```bash
339   # Run the server directly to test
340   node dist/index.js
341   ```
342 
343   If it connects to MySQL successfully, you're ready to use it with Claude Desktop.
344 
345### Run in remote mode
346 
347To run in remote mode, you'll need to provide [environment variables](https://github.com/benborla/mcp-server-mysql?tab=readme-ov-file#environment-variables) to the npx script.
348 
3491. Create env file in preferred directory
350 
351   ```bash
352   # create .env file
353   touch .env
354   ```
355 
3562. Copy-paste [example file](https://github.com/benborla/mcp-server-mysql/blob/main/.env) from this repository
3573. Set the MySQL credentials to match your environment
3584. Set `IS_REMOTE_MCP=true`
3595. Set `REMOTE_SECRET_KEY` to a secure string.
3606. Provide custom `PORT` if needed. Default is 3000.
3617. Load variables in current session:
362 
363   ```bash
364   source .env
365   ```
366 
3678. Run the server
368 
369   ```bash
370   npx @benborla29/mcp-server-mysql
371   ```
372 
3739. Configure your agent to connect to the MCP with the next configuration:
374 
375   ```json
376   {
377     "mcpServers": {
378       "mysql": {
379         "url": "http://your-host:3000/mcp",
380         "type": "streamableHttp",
381         "headers": {
382           "Authorization": "Bearer <REMOTE_SECRET_KEY>"
383         }
384       }
385     }
386   }
387   ```
388 
389## Components
390 
391### Tools
392 
393- **mysql_query**
394  - Execute SQL queries against the connected database
395  - Input: `sql` (string): The SQL query to execute
396  - By default, limited to READ ONLY operations
397  - Optional write operations (when enabled via configuration):
398    - INSERT: Add new data to tables (requires `ALLOW_INSERT_OPERATION=true`)
399    - UPDATE: Modify existing data (requires `ALLOW_UPDATE_OPERATION=true`)
400    - DELETE: Remove data (requires `ALLOW_DELETE_OPERATION=true`)
401  - All operations are executed within a transaction with proper commit/rollback handling
402  - Supports prepared statements for secure parameter handling
403  - Configurable query timeouts and result pagination
404  - Built-in query execution statistics
405 
406### Resources
407 
408The server provides comprehensive database information:
409 
410- **Table Schemas**
411  - JSON schema information for each table
412  - Column names and data types
413  - Index information and constraints
414  - Foreign key relationships
415  - Table statistics and metrics
416  - Automatically discovered from database metadata
417 
418### Security Features
419 
420- SQL injection prevention through prepared statements
421- Query whitelisting/blacklisting capabilities
422- Rate limiting for query execution
423- Query complexity analysis
424- Configurable connection encryption
425- Read-only transaction enforcement
426 
427### Performance Optimizations
428 
429- Optimized connection pooling
430- Query result caching
431- Large result set streaming
432- Query execution plan analysis
433- Configurable query timeouts
434 
435### Monitoring and Debugging
436 
437- Comprehensive query logging
438- Performance metrics collection
439- Error tracking and reporting
440- Health check endpoints
441- Query execution statistics
442 
443## Configuration
444 
445### Automatic Configuration with Smithery
446 
447If you installed using Smithery, your configuration is already set up. You can view or modify it with:
448 
449```bash
450smithery configure @benborla29/mcp-server-mysql
451```
452 
453When reconfiguring, you can update any of the MySQL connection details as well as the write operation settings:
454 
455- **Basic connection settings**:
456  - MySQL Host, Port, User, Password, Database
457  - SSL/TLS configuration (if your database requires secure connections)
458 
459- **Write operation permissions**:
460  - Allow INSERT Operations: Set to true if you want to allow adding new data
461  - Allow UPDATE Operations: Set to true if you want to allow updating existing data
462  - Allow DELETE Operations: Set to true if you want to allow deleting data
463 
464For security reasons, all write operations are disabled by default. Only enable these settings if you specifically need Claude to modify your database data.
465 
466### Advanced Configuration Options
467 
468For more control over the MCP server's behavior, you can use these advanced configuration options:
469 
470```json
471{
472  "mcpServers": {
473    "mcp_server_mysql": {
474      "command": "/path/to/npx/binary/npx",
475      "args": [
476        "-y",
477        "@benborla29/mcp-server-mysql"
478      ],
479      "env": {
480        // Basic connection settings
481        "MYSQL_HOST": "127.0.0.1",
482        "MYSQL_PORT": "3306",
483        "MYSQL_USER": "root",
484        "MYSQL_PASS": "",
485        "MYSQL_DB": "db_name",
486        "PATH": "/path/to/node/bin:/usr/bin:/bin",
487 
488        // Performance settings
489        "MYSQL_POOL_SIZE": "10",
490        "MYSQL_QUERY_TIMEOUT": "30000",
491        "MYSQL_CACHE_TTL": "60000",
492 
493        // Security settings
494        "MYSQL_RATE_LIMIT": "100",
495        "MYSQL_MAX_QUERY_COMPLEXITY": "1000",
496        "MYSQL_SSL": "true",
497 
498        // Monitoring settings
499        "ENABLE_LOGGING": "true",
500        "MYSQL_LOG_LEVEL": "info",
501        "MYSQL_METRICS_ENABLED": "true",
502 
503        // Write operation flags
504        "ALLOW_INSERT_OPERATION": "false",
505        "ALLOW_UPDATE_OPERATION": "false",
506        "ALLOW_DELETE_OPERATION": "false"
507      }
508    }
509  }
510}
511```
512 
513## Environment Variables
514 
515### Basic Connection
516 
517- `MYSQL_SOCKET_PATH`: Unix socket path for local connections (e.g., "/tmp/mysql.sock")
518- `MYSQL_HOST`: MySQL server host (default: "127.0.0.1") - ignored if MYSQL_SOCKET_PATH is set
519- `MYSQL_PORT`: MySQL server port (default: "3306") - ignored if MYSQL_SOCKET_PATH is set
520- `MYSQL_USER`: MySQL username (default: "root")
521- `MYSQL_PASS`: MySQL password
522- `MYSQL_DB`: Target database name (leave empty for multi-DB mode)
523 
524#### Alternative: Connection String
525 
526For scenarios requiring frequent credential rotation or temporary connections, you can use a MySQL connection string instead of individual environment variables:
527 
528- `MYSQL_CONNECTION_STRING`: MySQL CLI-format connection string (e.g., `mysql --default-auth=mysql_native_password -A -hHOST -PPORT -uUSER -pPASS database_name`)
529 
530When `MYSQL_CONNECTION_STRING` is provided, it takes precedence over individual connection settings. This is particularly useful for:
531 
532- Rotating credentials that expire frequently
533- Temporary database connections
534- Quick testing with different database configurations
535 
536**Note:** For security, this should only be set via environment variables, not stored in version-controlled configuration files. Consider using the `prompt` input type in Claude Code's MCP configuration for credentials that expire.
537 
538### Performance Configuration
539 
540- `MYSQL_POOL_SIZE`: Connection pool size (default: "10")
541- `MYSQL_QUERY_TIMEOUT`: Query timeout in milliseconds (default: "30000")
542- `MYSQL_CACHE_TTL`: Cache time-to-live in milliseconds (default: "60000")
543- `MYSQL_QUEUE_LIMIT`: Maximum number of queued connection requests (default: "100")
544- `MYSQL_CONNECT_TIMEOUT`: Connection timeout in milliseconds (default: "10000")
545 
546### Security Configuration
547 
548- `MYSQL_RATE_LIMIT`: Maximum queries per minute (default: "100")
549- `MYSQL_MAX_QUERY_COMPLEXITY`: Maximum query complexity score (default: "1000")
550- `MYSQL_SSL`: Enable SSL/TLS encryption (default: "false")
551- `ALLOW_INSERT_OPERATION`: Enable INSERT operations (default: "false")
552- `ALLOW_UPDATE_OPERATION`: Enable UPDATE operations (default: "false")
553- `ALLOW_DELETE_OPERATION`: Enable DELETE operations (default: "false")
554- `ALLOW_DDL_OPERATION`: Enable DDL operations (default: "false")
555- `MYSQL_DISABLE_READ_ONLY_TRANSACTIONS`: **[NEW]** Disable read-only transaction enforcement (default: "false") ⚠️ **Security Warning:** Only enable this if you need full write capabilities and trust the LLM with your database
556- `SCHEMA_INSERT_PERMISSIONS`: Schema-specific INSERT permissions
557- `SCHEMA_UPDATE_PERMISSIONS`: Schema-specific UPDATE permissions
558- `SCHEMA_DELETE_PERMISSIONS`: Schema-specific DELETE permissions
559- `SCHEMA_DDL_PERMISSIONS`: Schema-specific DDL permissions
560- `MULTI_DB_WRITE_MODE`: Enable write operations in multi-DB mode (default: "false")
561 
562### Timezone and Date Configuration
563 
564- `MYSQL_TIMEZONE`: Set the timezone for date/time values. Accepts formats like `+08:00` (UTC+8), `-05:00` (UTC-5), `Z` (UTC), or `local` (system timezone). Useful for ensuring consistent date/time handling across different server locations.
565- `MYSQL_DATE_STRINGS`: When set to `"true"`, returns date/datetime values as strings instead of JavaScript Date objects. This preserves the exact database values without any timezone conversion, which is particularly useful for:
566  - Applications that need precise control over date formatting
567  - Cross-timezone database operations
568  - Avoiding JavaScript Date timezone quirks
569 
570### Monitoring Configuration
571 
572- `MYSQL_ENABLE_LOGGING`: Enable query logging (default: "false")
573- `MYSQL_LOG_LEVEL`: Logging level (default: "info")
574- `MYSQL_METRICS_ENABLED`: Enable performance metrics (default: "false")
575 
576### Remote MCP Configuration
577 
578- `IS_REMOTE_MCP`: Enable remote MCP mode (default: "false")
579- `REMOTE_SECRET_KEY`: Secret key for remote MCP authentication (default: ""). If not provided, remote MCP mode will be disabled.
580- `PORT`: Port number for the remote MCP server (default: 3000)
581 
582## Multi-DB Mode
583 
584MCP-Server-MySQL supports connecting to multiple databases when no specific database is set. This allows the LLM to query any database the MySQL user has access to. For full details, see [README-MULTI-DB.md](./README-MULTI-DB.md).
585 
586### Enabling Multi-DB Mode
587 
588To enable multi-DB mode, simply leave the `MYSQL_DB` environment variable empty. In multi-DB mode, queries require schema qualification:
589 
590```sql
591-- Use fully qualified table names
592SELECT * FROM database_name.table_name;
593 
594-- Or use USE statements to switch between databases
595USE database_name;
596SELECT * FROM table_name;
597```
598 
599## Schema-Specific Permissions
600 
601For fine-grained control over database operations, MCP-Server-MySQL now supports schema-specific permissions. This allows different databases to have different levels of access (read-only, read-write, etc.).
602 
603### Configuration Example
604 
605```txt
606SCHEMA_INSERT_PERMISSIONS=development:true,test:true,production:false
607SCHEMA_UPDATE_PERMISSIONS=development:true,test:true,production:false
608SCHEMA_DELETE_PERMISSIONS=development:false,test:true,production:false
609SCHEMA_DDL_PERMISSIONS=development:false,test:true,production:false
610```
611 
612For complete details and security recommendations, see [README-MULTI-DB.md](./README-MULTI-DB.md).
613 
614## Testing
615 
616### Database Setup
617 
618Before running tests, you need to set up the test database and seed it with test data:
619 
6201. **Create Test Database and User**
621 
622   ```sql
623   -- Connect as root and create test database
624   CREATE DATABASE IF NOT EXISTS mcp_test;
625 
626   -- Create test user with appropriate permissions
627   CREATE USER IF NOT EXISTS 'mcp_test'@'localhost' IDENTIFIED BY 'mcp_test_password';
628   GRANT ALL PRIVILEGES ON mcp_test.* TO 'mcp_test'@'localhost';
629   FLUSH PRIVILEGES;
630   ```
631 
6322. **Run Database Setup Script**
633 
634   ```bash
635   # Run the database setup script
636   pnpm run setup:test:db
637   ```
638 
639   This will create the necessary tables and seed data. The script is located in `scripts/setup-test-db.ts`
640 
6413. **Configure Test Environment**
642   Create a `.env.test` file in the project root (if not existing):
643 
644   ```env
645   MYSQL_HOST=127.0.0.1
646   MYSQL_PORT=3306
647   MYSQL_USER=mcp_test
648   MYSQL_PASS=mcp_test_password
649   MYSQL_DB=mcp_test
650   ```
651 
6524. **Update package.json Scripts**
653   Add these scripts to your package.json:
654 
655   ```json
656   {
657     "scripts": {
658       "setup:test:db": "ts-node scripts/setup-test-db.ts",
659       "pretest": "pnpm run setup:test:db",
660       "test": "vitest run",
661       "test:watch": "vitest",
662       "test:coverage": "vitest run --coverage"
663     }
664   }
665   ```
666 
667### Running Tests
668 
669The project includes a comprehensive test suite to ensure functionality and reliability:
670 
671```bash
672# First-time setup
673pnpm run setup:test:db
674 
675# Run all tests
676pnpm test
677```
678 
679## Running evals
680 
681The evals package loads an mcp client that then runs the index.ts file, so there is no need to rebuild between tests. You can load environment variables by prefixing the npx command. Full documentation can be found at [MCP Evals](https://www.mcpevals.io/docs).
682 
683```bash
684OPENAI_API_KEY=your-key  npx mcp-eval evals.ts index.ts
685```
686 
687## Troubleshooting
688 
689### Common Issues
690 
6911. **Connection Issues**
692   - Verify MySQL server is running and accessible
693   - Check credentials and permissions
694   - Ensure SSL/TLS configuration is correct if enabled
695   - Try connecting with a MySQL client to confirm access
696 
6972. **Performance Issues**
698   - Adjust connection pool size
699   - Configure query timeout values
700   - Enable query caching if needed
701   - Check query complexity settings
702   - Monitor server resource usage
703 
7043. **Security Restrictions**
705   - Review rate limiting configuration
706   - Check query whitelist/blacklist settings
707   - Verify SSL/TLS settings
708   - Ensure the user has appropriate MySQL permissions
709 
7104. **Path Resolution**
711   If you encounter an error "Could not connect to MCP server mcp-server-mysql", explicitly set the path of all required binaries:
712 
713   ```json
714   {
715     "env": {
716       "PATH": "/path/to/node/bin:/usr/bin:/bin"
717     }
718   }
719   ```
720 
721   *Where can I find my `node` bin path*
722   Run the following command to get it:
723 
724   For **PATH**
725 
726   ```bash
727   echo "$(which node)/../"
728   ```
729 
730   For **NODE_PATH**
731 
732   ```bash
733   echo "$(which node)/../../lib/node_modules"
734   ```
735 
7365. **Claude Desktop Specific Issues**
737   - If you see "Server disconnected" logs in Claude Desktop, check the logs at `~/Library/Logs/Claude/mcp-server-mcp_server_mysql.log`
738   - Ensure you're using the absolute path to both the Node binary and the server script
739   - Check if your `.env` file is being properly loaded; use explicit environment variables in the configuration
740   - Try running the server directly from the command line to see if there are connection issues
741   - If you need write operations (INSERT, UPDATE, DELETE), set the appropriate flags to "true" in your configuration:
742 
743     ```json
744     "env": {
745       "ALLOW_INSERT_OPERATION": "true",  // Enable INSERT operations
746       "ALLOW_UPDATE_OPERATION": "true",  // Enable UPDATE operations
747       "ALLOW_DELETE_OPERATION": "true"   // Enable DELETE operations
748     }
749     ```
750 
751   - Ensure your MySQL user has the appropriate permissions for the operations you're enabling
752   - For direct execution configuration, use:
753 
754     ```json
755     {
756       "mcpServers": {
757         "mcp_server_mysql": {
758           "command": "/full/path/to/node",
759           "args": [
760             "/full/path/to/mcp-server-mysql/dist/index.js"
761           ],
762           "env": {
763             "MYSQL_HOST": "127.0.0.1",
764             "MYSQL_PORT": "3306",
765             "MYSQL_USER": "root",
766             "MYSQL_PASS": "your_password",
767             "MYSQL_DB": "your_database"
768           }
769         }
770       }
771     }
772     ```
773 
7746. **Authentication Issues**
775   - For MySQL 8.0+, ensure the server supports the `caching_sha2_password` authentication plugin
776   - Check if your MySQL user is configured with the correct authentication method
777   - Try creating a user with legacy authentication if needed:
778 
779     ```sql
780     CREATE USER 'user'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';
781     ```
782 
783     @lizhuangs
784 
7857. I am encountering `Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'dotenv' imported from` error
786   try this workaround:
787 
788   ```bash
789   npx -y -p @benborla29/mcp-server-mysql -p dotenv mcp-server-mysql
790   ```
791 
792   Thanks to @lizhuangs
793 
794## Contributing
795 
796Contributions are welcome! Please feel free to submit a Pull Request to
797[https://github.com/benborla/mcp-server-mysql](https://github.com/benborla/mcp-server-mysql)
798 
799## Many Thanks to the following Contributors
800 
801[![Contributors](https://contrib.rocks/image?repo=benborla/mcp-server-mysql)](https://github.com/benborla/mcp-server-mysql/graphs/contributors)
802 
803### Development Setup
804 
8051. Clone the repository
8062. Install dependencies: `pnpm install`
8073. Build the project: `pnpm run build`
8084. Run tests: `pnpm test`
809 
810### Project Roadmap
811 
812We're actively working on enhancing this MCP server. Check our [CHANGELOG.md](./CHANGELOG.md) for details on planned features, including:
813 
814- Enhanced query capabilities with prepared statements
815- Advanced security features
816- Performance optimizations
817- Comprehensive monitoring
818- Expanded schema information
819 
820If you'd like to contribute to any of these areas, please check the issues on GitHub or open a new one to discuss your ideas.
821 
822### Submitting Changes
823 
8241. Fork the repository
8252. Create a feature branch: `git checkout -b feature/your-feature-name`
8263. Commit your changes: `git commit -am 'Add some feature'`
8274. Push to the branch: `git push origin feature/your-feature-name`
8285. Submit a pull request
829 
830## License
831 
832This MCP server is licensed under the MIT License. See the LICENSE file for details.
833