Verified MCP server: MySQL
The tool list below is a live capture from the running server; an authenticated tool call is still pending credentials.
The short answer
Last verified 2026-08-03
The MySQL MCP server gives an AI assistant one door into a MySQL database: a single tool, mysql_query, that runs SQL and hands back the rows. It is community-maintained by Ben Borla, not by MySQL and not by the Model Context Protocol project, and it is the most installed MySQL MCP server on npm at 12,075 downloads in the week ending 2026-08-01, with 2,003 stars and a repository last pushed on 2026-07-27. The credential is not an API key: it is a database connection you already own, the host, port, username, password and database name, handed over as environment variables. We ran it on a Mac, spoke the protocol to it, and it answered with exactly one tool, which is the table below word for word. This Mac runs no MySQL, so the query call could not complete: the server quits the moment its startup connection test is refused, and that refusal is printed further down this page. The tool count is a live reading; a working query is still pending a database to point it at. [1][2][3][4][5]
Verification
Method
We spawned the server with npx over stdio with MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASS and MYSQL_DB set to placeholder values, completed the MCP initialize handshake, and called tools/list: it answered with exactly one tool, and the table below is that answer word for word. The server printed nothing on the error stream, so the banner shown here is its own identification line from the initialize response. The tools were enumerated live with placeholder credentials, and an authenticated call is still pending a reachable MySQL server plus its connection settings in the MYSQL_HOST / MYSQL_PORT / MYSQL_USER / MYSQL_PASS / MYSQL_DB environment variables, because this is a database connection and not an API key. Our mysql_query call for SELECT 1 came back with no response at all: this Mac runs no MySQL, and the server exits the instant its startup connection test is refused, so we re-ran the same command with the server's own ENABLE_LOGGING flag to capture the refusal in its own words, quoted below and in the troubleshooting section.
Startup banner
{"result":{"protocolVersion":"2024-11-05","capabilities":{"resources":{},"tools":{"mysql_query":{"description":"[MySQL MCP Server [vundefined]] Run SQL queries against MySQL database (READ-ONLY)","inputSchema":{"type":"object","properties":{"sql":{"type":"string","description":"The SQL query to execute"}},"required":["sql"]},"annotations":{"readOnlyHint":true,"idempotentHint":true,"destructiveHint":false,"openWorldHint":false,"title":"MySQL Query"}}}},"serverInfo":{"name":"MySQL MCP Server","version":"1.0.0"}},"jsonrpc":"2.0","id":1}One real tool call
tools/call mysql_query {"sql":"SELECT 1"}Fatal error during server startup: Error: connect ECONNREFUSED 127.0.0.1:3306
at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1706:16) {
errno: -61,
code: 'ECONNREFUSED',Real lines from the captured result: enough to prove the call answered.
Tools
The server answered tools/list with 1 tools on 2026-08-03. The names, descriptions and parameters below are its own words, copied from that response and never edited.
| Tool | What it does |
|---|---|
| mysql_querysql* | [MySQL MCP Server [vundefined]] Run SQL queries against MySQL database (READ-ONLY) |
Parameters marked with * are required.
Setup
Copy the block for the app you use. Each one is the configuration this server was verified with.
Open the file ~/Library/Application Support/Claude/claude_desktop_config.json (in Claude Desktop: Settings, then Developer, then Edit Config) and add:
{
"mcpServers": {
"mcp_server_mysql": {
"command": "npx",
"args": ["-y", "@benborla29/mcp-server-mysql"],
"env": {
"MYSQL_HOST": "127.0.0.1",
"MYSQL_PORT": "3306",
"MYSQL_USER": "root",
"MYSQL_PASS": "your_password",
"MYSQL_DB": "your_database"
}
}
}
}Replace the five values with the details of a database you can already reach, then quit and reopen Claude Desktop. Leave MYSQL_DB filled in: without it the server switches itself to multi-database mode. [5][8]
One command in your terminal:
claude mcp add mcp_server_mysql \ -e MYSQL_HOST="127.0.0.1" \ -e MYSQL_PORT="3306" \ -e MYSQL_USER="root" \ -e MYSQL_PASS="your_password" \ -e MYSQL_DB="your_database" \ -- npx @benborla29/mcp-server-mysql
Each -e sets one environment variable, and everything after the double dash is the exact command Claude Code will run. The docs suggest keeping the default local scope, or -s user for every project, so the password stays out of a shared file. [5][7][9]
Add to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json inside one project:
{
"mcpServers": {
"mcp_server_mysql": {
"command": "npx",
"args": ["-y", "@benborla29/mcp-server-mysql"],
"env": {
"MYSQL_HOST": "127.0.0.1",
"MYSQL_PORT": "3306",
"MYSQL_USER": "root",
"MYSQL_PASS": "your_password",
"MYSQL_DB": "your_database"
}
}
}
}Cursor picks the file up on restart. A project file is shared with anyone who has the repository, so put the password in the personal file at ~/.cursor/mcp.json. [10][5]
No JSON file and no terminal. In Routines: Settings, then Assistant, then Connections, then Add MCP Server. Switch the form to Command (stdio) and enter:
Name MySQL Command npx Arguments -y @benborla29/mcp-server-mysql Environment Variables MYSQL_HOST 127.0.0.1 MYSQL_PORT 3306 MYSQL_USER root MYSQL_PASS your_password MYSQL_DB your_database
The five Environment Variables rows are the credential: fill them with the details of a database you can already reach. Click Test Connection first: a working server answers with its tool count, one for this server. [11][7]
No terminal needed
If you have never opened Terminal and never want to, this is your path. Routines is a Mac app that runs MCP servers for you: fill in a few fields once, and this server's tool is available to your AI in chat and in scheduled routines.
01
Download the app from getroutines.ai/download, drag it to Applications, and sign in.
02
Click your account at the bottom of the sidebar and choose Settings. Open the Assistant section, then the Connections tab, scroll to MCP Servers, and click Add MCP Server.
03
Switch the form to Command (stdio): this server is a command, not a web address. Name: MySQL. Command: npx. Arguments: -y @benborla29/mcp-server-mysql, with nothing after the package name.
04
This is a database connection, not an API key: there is nothing to sign up for and no token to generate. You need a MySQL server this Mac can actually reach, and an existing MySQL username and password for it. Add five Environment Variables rows: MYSQL_HOST (127.0.0.1 for a database on this Mac, otherwise the server address), MYSQL_PORT (3306 unless you were told otherwise), MYSQL_USER, MYSQL_PASS, and MYSQL_DB, the name of the one database you want the assistant to see. Ask whoever runs the database for a read-only user if you are not sure.
05
Click Test Connection: Routines starts the server and reports how many tools it found, one for this server. If the test fails, the connection details are wrong or the database is not reachable from this Mac; the troubleshooting section below has the exact errors. Then click Add Server.
06
The tool works in chat right away: ask a question in plain English and the assistant writes the SQL. To let a scheduled routine use it, open the routine, find the Tools & connections card, and tick the server under Apps.
Routine ideas
Once the server is connected, a scheduled routine can use its tools while you are away. Copy a prompt, paste it into Routines, and pick a time.
Every Monday at 8:00, query the database for last week's orders, and write me a short summary with the total revenue, the number of orders, the five best selling products, and how each number compares with the week before.
Every weekday at 9:00, count the accounts created in the database yesterday, compare that with the daily average of the last 30 days, and tell me in two sentences whether signups are up or down and by how much.
Every evening at 18:00, check the database for rows that look wrong: customers with no email address, orders with no customer, and prices below zero. List what you find, with a count for each problem, and say nothing if everything is clean.
Troubleshooting
Real errors captured during the verification run, printed exactly as the server returned them.
What you see
Fatal error during server startup: Error: connect ECONNREFUSED 127.0.0.1:3306
at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1706:16) {
errno: -61,
code: 'ECONNREFUSED',
syscall: 'connect',
address: '127.0.0.1',
port: 3306,
fatal: true
}The fix
This is what we hit on the test Mac, and it is the failure most people meet first. The server tests the database connection on startup and exits immediately if that test fails, so your client shows a server that started and vanished. ECONNREFUSED means the address answered but nothing is listening on that port: MySQL is not running, or MYSQL_HOST and MYSQL_PORT point somewhere else. Start the database, or correct the two values, and try again. The server prints nothing at all by default; add ENABLE_LOGGING=true to your environment variables to see the message above.
What you see
Fatal error during server startup: Error: getaddrinfo ENOTFOUND my-database.invalid
at GetAddrInfoReqWrap.onlookupall [as oncomplete] (node:dns:122:26) {
errno: -3008,
code: 'ENOTFOUND',
syscall: 'getaddrinfo',
hostname: 'my-database.invalid',
fatal: true
}The fix
We triggered this on purpose with a host name that does not exist. ENOTFOUND means the name in MYSQL_HOST could not be looked up at all, so it is almost always a spelling mistake or a private address that only resolves on a company network. Check the spelling, and for a database on this same Mac use 127.0.0.1.
What you see
Multi-DB mode detected - enabling read-only mode for safety
The fix
We left MYSQL_DB empty and the server switched itself to multi-database mode, where queries are not confined to one database. It stays read-only in that mode, but it is wider access than most people intend. Set MYSQL_DB to the single database you want the assistant to see.
The fix
The npx command belongs to Node.js. If Node is not installed on your Mac, every client on this page fails at the spawn step before the server can say anything. Install Node from nodejs.org, restart your MCP client, and try again.
FAQ
It is a small program that connects an AI assistant such as Claude to a MySQL database. Once connected, you ask a question in plain English, the assistant writes the SQL, the server runs it against your database and hands the rows back. It runs as a local process on your Mac and talks to your AI app over stdio. It is community software by Ben Borla, not an official MySQL product. [5][1]
Exactly one, and we counted it live: mysql_query, which takes a single sql parameter and runs it. That is the whole surface. Instead of a tool per action, this server gives the assistant one door into the database and lets SQL do the rest, which is why the permissions you give its MySQL user matter more here than the tool list does.
It is read-only by default: the tool description it reported to us ends in READ-ONLY, and writing is opt-in through the ALLOW_INSERT_OPERATION, ALLOW_UPDATE_OPERATION, ALLOW_DELETE_OPERATION and ALLOW_DDL_OPERATION environment variables, each of which defaults to false. The real risk is scope, because one tool that accepts any SQL sees whatever its MySQL user can see. Give it a user with rights to one database and nothing else, leave the four write flags alone unless you truly need them, and never point it at a production database you cannot restore. [6]
No. In Routines you fill in a few fields in Settings and click Test Connection; the walkthrough above shows every click. Claude Desktop and Cursor each need a small JSON file edited once. Only Claude Code is terminal-first by nature. [11][8]
No. There is no sign-up and no token to generate: the credential is a database connection you already own, the host, port, username, password and database name, entered as environment variables. What you do need is a MySQL server your Mac can reach. Our own test Mac had none, which is exactly why the sample call on this page failed instead of returning rows. [7]
Both numbers are real and we captured both. The npm registry publishes the package at 2.0.9. Over MCP, the running server self-reports its own name and version in the handshake, MySQL MCP Server 1.0.0, a number the maintainer has not moved with the releases. Same code, two counters. The tool description carries the same seam: it starts with the literal text [MySQL MCP Server [vundefined]] because a version placeholder in it never got filled in. [1]
Any MCP client that can launch a local stdio server: Claude Desktop, Claude Code, Cursor, and Routines all can, and the exact config for each is above. The server itself is the same in every client; only the place you paste the config differs. It can also be run in a remote mode over HTTP with a bearer token, which is a setup for teams rather than for one Mac. [8][9][10][11][7]
Sources
Anything on this page we did not observe in the run is linked here, with the date we read it. The run itself is the receipt for the rest.
[1]
Latest version 2.0.9, published 2026-06-19. Author Ben Borla, npm maintainer benborla29.
[2]
[3]
2,003 stars and an MIT license at access time. Read from the repository page because the GitHub API was rate limited.
[4]
Most recent commit entry dated 2026-07-27, used as the last-push date.
[5]
The Claude Code command, the JSON config block, the MIT license line, and the read-only-by-default framing.
[6]
The security and permissions table: ALLOW_INSERT_OPERATION, ALLOW_UPDATE_OPERATION, ALLOW_DELETE_OPERATION and ALLOW_DDL_OPERATION all default to false.
[7]
Credential setup per client, scope advice for keeping the password private, and the remote HTTP mode with a bearer token.
[8]
Where the Claude Desktop config file lives and how to edit it.
[9]
The claude mcp add syntax for local stdio servers, including -e for environment variables.
[10]
[11]
How Routines runs one-click OAuth connectors and any MCP server.
This page describes MySQL as it behaved in one dated run on one Mac. Versions move: if something here no longer matches what you see, the capture date at the top says how old the reading is.
Behind this directory
Routines, the app behind this directory, runs MCP servers like this one without a terminal: see how connectors work. Your notes stay markdown files on your Mac, there is no cloud bill, and it works offline. Download Routines