MySQL+MCP+ECONNREFUSED+MySQL+not+running+or+wrong+MYSQL+HOST

Not specified by the original author.

TL;DR: ECONNREFUSED means nothing is listening where the MCP server is looking. Start MySQL, then make sure MYSQL_HOST and MYSQL_PORT in the client config match where it actually listens. The defaults (YOUR_HOST:3306) are wrong for Docker and remote setups.

Error: connect ECONNREFUSED the loopback address:3306

Fix it

1. Check MySQL is running:

# Linux
sudo systemctl status mysql
# macOS (Homebrew)
brew services list
# Docker
docker ps | grep mysql

2. Check what it listens on:

sudo netstat -tlnp | grep 3306

Expected: a line showing mysqld on 3306 (or your configured port).

3. Set the real address in the client config env block. Docker on the host: host.YOUR_HOST. Docker Compose service: the service name. Remote: the hostname or IP.

{
  "env": {
    "MYSQL_HOST": "host.YOUR_HOST",
    "MYSQL_PORT": "3306"
  }
}

4. Restart the MCP client.

   Expected: the refused error is gone. Next failure, if any, will be auth, which is progress.

When to use this

• The error is ECONNREFUSED mentioning the MySQL host and port.
• mysql -h [host] from a terminal also fails to connect.

When NOT to use this

• The error is ER_ACCESS_DENIED_ERROR. The server is reachable; credentials are wrong.
• The error is a timeout (ETIMEDOUT). That is firewall or routing, not a refused connection.

Compatibility

• benborla/mcp-server-mysql.
• MySQL 5.7, 8.x, MariaDB, in Docker or on the host.

Why it happens

Connection refused is the OS telling you the SYN packet arrived but no process accepted it. Either MySQL is down, or it is up but bound to a different interface or port than the config says. MCP defaults assume a local MySQL on 3306, which breaks the moment MySQL lives in Docker or on another machine.

Edge cases

• MySQL in Docker without a published port is unreachable from the host. Add -p 3306:3306.
• bind-address = the loopback address in my.cnf blocks remote connections even when the port is open. Set it to the all-interfaces address for remote access (with proper grants).
• Skip-networking enabled means TCP is off entirely. The MCP server needs TCP; use a socket only if the server supports it.

ECONNREFUSED is the standard TCP connection-refused error when the MySQL server is not running or not listening at the configured host and port, documented in MySQL troubleshooting guides with the fix of starting the MySQL service and verifying the host and port. The benborla/mcp-server-mysql server reads MYSQLHOST and MYSQLPORT from the environment, defaulting to YOUR_HOST:3306, so a MySQL running elsewhere or on a different port produces this exact error. Source: https://github.com/benborla/mcp-server-mysql

Not specified by the original author.

TL;DR: Access denied for user means the MySQL MCP server is sending the wrong username or password, or the user is not allowed to connect from the client's host. Test the exact credentials with the mysql CLI, fix MYSQL_USER / MYSQL_PASS in the client config env block, restart.

ER_ACCESS_DENIED_ERROR: Access denied for user 'appuser'@'YOUR_HOST' (using password value YES)

Fix it

1. Test the credentials outside the MCP layer with the exact same values:

mysql -h YOUR_MYSQL_HOST -u appuser -p'yourpassword' -e "SELECT 1;"

Expected: 1. If this fails, the problem is the credentials or grants, not the MCP server.

2. Check the host part. 'appuser'@'YOUR_HOST' and 'appuser'@'%' are different MySQL users. If the MCP server connects over TCP from another host, the user needs a matching host entry:

CREATE USER 'appuser'@'%' IDENTIFIED BY 'yourpassword';
GRANT SELECT ON mydb.* TO 'appuser'@'%';
FLUSH PRIVILEGES;

3. Update the client config env block:

{
  "env": {
    "MYSQL_HOST": "YOUR_MYSQL_HOST",
    "MYSQL_PORT": "3306",
    "MYSQL_USER": "appuser",
    "MYSQL_PASS": "yourpassword",
    "MYSQL_DB": "mydb"
  }
}

4. Restart the MCP client.

   Expected: the server connects and tools work.

When to use this

• Every tool call fails with ER_ACCESS_DENIED_ERROR.
• The mysql CLI with the same credentials also fails (proves it is credentials, not MCP).

When NOT to use this

• The error is ER_BAD_DB_ERROR: Unknown database. Auth worked; the database name is wrong.
• The error is ECONNREFUSED. The server is unreachable.
• The error mentions caching_sha2_password. That is an auth-plugin problem, different fix.

Compatibility

• benborla/mcp-server-mysql (MYSQL_HOST/PORT/USER/PASS/DB env config).
• MySQL 5.7, 8.x, MariaDB.

Why it happens

MySQL authenticates the pair of (username, host), not just the username. MCP configs get copied between machines, so the password is right but the host the server connects from does not match any grant. The (using password value YES) detail tells you a password was sent; the fix is aligning the user, password, and host grant.

Edge cases

• Special characters in MYSQL_PASS inside JSON need JSON escaping. A # or ! is fine; a \ or " needs escaping.
• MySQL 8 defaults to caching_sha2_password. Old clients fail with a plugin error, not access denied. If you see the plugin named, that is your problem instead.
• Skip-name-resolve servers: use IP addresses in host grants, not hostnames.

The benborla/mcp-server-mysql server authenticates with MYSQLUSER and MYSQLPASS environment variables. ERACCESSDENIED_ERROR: Access denied for user is the standard MySQL authentication failure, documented across MySQL troubleshooting guides with the fix of verifying the database username and password in the configuration and ensuring the MySQL server is running. For the MCP server the credentials live in the client config env block, not a .env file the server reads itself. Source: https://github.com/benborla/mcp-server-mysql

Not specified by the original author.

TL;DR: Connection refused means ChromaDB is not running where the MCP server is looking. Start ChromaDB, confirm CHROMA_HOST and CHROMA_PORT match, restart the client.

Connection refused

(When the Chroma MCP server dials the ChromaDB instance.)

Fix it

1. Start ChromaDB if it is not running:

chroma run --path ./chroma_db

Or with Docker:

docker run -d -p 8000:8000 chromadb/chroma

2. Verify it answers:

curl http://YOUR_CHROMA_HOST:8000/api/v2/heartbeat

Expected: a JSON heartbeat response.

3. Match the MCP server config to it:

{
  "env": {
    "CHROMA_CLIENT_TYPE": "http",
    "CHROMA_HOST": "YOUR_CHROMA_HOST",
    "CHROMA_PORT": "8000"
  }
}

4. Restart the MCP client.

   Expected: the server connects and collection tools work.

When to use this

• The MCP server fails with connection refused mentioning the Chroma host/port.
• The heartbeat curl also fails (proves ChromaDB is down, not the MCP server).

When NOT to use this

• The heartbeat works but the MCP server still fails. Then the host/port in the client config is wrong.
• Collection not found errors. ChromaDB is up; the collection name is wrong.

Compatibility

• chroma-mcp in http client mode, rkilchmn/chroma-mcp-server.
• ChromaDB local (chroma run) and Docker.

Why it happens

The MCP server is a client of ChromaDB, not a bundle of it. Fresh setups configure the MCP side but never start the database, or start it on a different port. The default port 8000 is a convention, not a guarantee.

Edge cases

• In Docker, the MCP server needs the container or service name as host, not YOUR_HOST.
• chroma run defaults to port 8000. If something else holds 8000, ChromaDB fails to start. Check with lsof -i :8000.
• For embedded/persistent mode, the server uses a data directory instead of host/port. Do not mix the two modes.

The chroma-mcp-server troubleshooting section (rkilchmn/chroma-mcp-server) lists connection refused as a common issue with the fix: ensure ChromaDB is running on the specified host/port. The server supports both local persistent and remote ChromaDB instances, configured via host and port, and a ChromaDB that was never started (or started on a different port) produces connection refused through the MCP tools. Source: https://github.com/rkilchmn/chroma-mcp-server