Troubleshooting Guide

Connection Issues

Oracle Connection Errors

ORA-12170: TNS:Connect timeout occurred

Cause: The Oracle server is unreachable or a firewall is blocking the connection.Solutions:

Verify the Oracle server is running:

# Check if Oracle listener is active
lsnrctl status

Test network connectivity:

# Test from Docker container
docker run --rm -it alpine nc -zv host.docker.internal 1521

Check firewall rules:

# Allow Oracle port
sudo ufw allow 1521/tcp

On macOS with Docker, use host.docker.internal instead of localhost:

{
  "args": ["mochoa/mcp-oracle", "host.docker.internal:1521/freepdb1"]
}

ORA-12541: TNS:no listener

Cause: The Oracle listener is not running or not configured correctly.Solutions:

Start the Oracle listener:
```
lsnrctl start
```

Verify listener configuration in listener.ora:

LISTENER =
  (DESCRIPTION_LIST =
    (DESCRIPTION =
      (ADDRESS = (PROTOCOL = TCP)(HOST = 0.0.0.0)(PORT = 1521))
    )
  )

Check if the correct port is being used:
```
lsnrctl status | grep PORT
```

ORA-01017: invalid username/password

Cause: Incorrect credentials or user doesn’t exist.Solutions:

Verify credentials are correct

Check if user exists:

SELECT username FROM dba_users WHERE username = 'MCP_READONLY';

Ensure password is set correctly:

ALTER USER mcp_readonly IDENTIFIED BY new_password;

Check environment variables:

docker run -i --rm \
  -e ORACLE_USER=correct_user \
  -e ORACLE_PASSWORD=correct_password \
  mochoa/mcp-oracle

MySQL Connection Errors

ECONNREFUSED: Connection refused

Cause: MySQL server is not running or not accessible.Solutions:

Verify MySQL is running:

sudo systemctl status mysql
# or
sudo service mysql status

Check MySQL is listening on the correct port:
```
sudo netstat -tlnp | grep 3306
```
Ensure MySQL is bound to the correct interface in my.cnf:
```
[mysqld]
bind-address = 0.0.0.0
```

Use host.docker.internal on macOS/Windows:

docker run -i --rm \
  -e MYSQL_USER=root \
  -e MYSQL_PASSWORD=pass \
  mochoa/mcp-mysql \
  host.docker.internal:3306/mydb

ER_ACCESS_DENIED_ERROR: Access denied for user

Cause: Invalid credentials or insufficient host permissions.Solutions:

Verify credentials:
```
mysql -u mcp_readonly -p -h localhost
```

Check user host permissions:

SELECT user, host FROM mysql.user WHERE user = 'mcp_readonly';

Grant access from Docker network:

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

Verify environment variables are set correctly:

{
  "env": {
    "MYSQL_USER": "mcp_readonly",
    "MYSQL_PASSWORD": "correct_password"
  }
}

ER_BAD_DB_ERROR: Unknown database

Cause: The specified database doesn’t exist.Solutions:

List available databases:
```
SHOW DATABASES;
```
Create the database:
```
CREATE DATABASE mydb;
```

Verify connection string:

# Correct format
host.docker.internal:3306/existing_db

MikroTik Connection Errors

Connection timeout

Cause: MikroTik API service is disabled or router is unreachable.Solutions:

Enable API service on MikroTik:

/ip service enable api
/ip service set api address=0.0.0.0/0

For SSL connections, enable API-SSL:
```
/ip service enable api-ssl
```

Test connectivity:

nc -zv 192.168.88.1 8728
# For SSL
nc -zv 192.168.88.1 8729

Check firewall rules on MikroTik:

/ip firewall filter print where dst-port=8728

Authentication failed

Cause: Invalid credentials or user doesn’t have API access.Solutions:

Verify user exists:
```
/user print
```

Ensure user has correct group:

/user set [find name=mcp_user] group=read

Test credentials manually:
```
# Use MikroTik API test tool or Winbox
```

Check environment variables:

docker run -i --rm \
  -e MK_USER=correct_user \
  -e MK_PASSWORD=correct_password \
  mochoa/mcp-mikrotik 192.168.88.1

Permission Errors

Oracle Permission Issues

ORA-00942: table or view does not exist

Cause: User doesn’t have SELECT permission on the table.Solutions:

Grant SELECT permission:

GRANT SELECT ON schema.table_name TO mcp_readonly;

Grant SELECT on entire schema:

BEGIN
  FOR t IN (SELECT table_name FROM dba_tables WHERE owner = 'SCHEMA_NAME') LOOP
    EXECUTE IMMEDIATE 'GRANT SELECT ON SCHEMA_NAME.' || t.table_name || ' TO mcp_readonly';
  END LOOP;
END;
/

ORA-01031: insufficient privileges (EXPLAIN)

Cause: User lacks SELECT_CATALOG_ROLE for explain plans.Solution:

GRANT SELECT_CATALOG_ROLE TO mcp_readonly;

ORA-00604: error occurred at recursive SQL level (AWR)

Cause: User lacks privileges for AWR package.Solution:

GRANT SELECT_CATALOG_ROLE TO mcp_readonly;
GRANT EXECUTE ON DBMS_WORKLOAD_REPOSITORY TO mcp_readonly;

MySQL Permission Issues

SELECT command denied

Cause: User doesn’t have SELECT privilege.Solutions:

Grant SELECT on specific tables:

GRANT SELECT ON mydb.users TO 'mcp_readonly'@'%';

Grant SELECT on entire database:

GRANT SELECT ON mydb.* TO 'mcp_readonly'@'%';
FLUSH PRIVILEGES;

Performance Schema access denied

Cause: User lacks access to performance_schema (needed for AWR).Solution:

GRANT SELECT ON performance_schema.* TO 'mcp_readonly'@'%';
FLUSH PRIVILEGES;

Docker Issues

docker: command not found

Cause: Docker is not installed or not in PATH.Solutions:

Install Docker Desktop (macOS/Windows) or Docker Engine (Linux)
Verify installation:
```
docker --version
```
Ensure Docker daemon is running:
```
sudo systemctl start docker
```

Cannot connect to Docker daemon

Cause: Docker daemon is not running or user lacks permissions.Solutions:

Start Docker daemon:
```
sudo systemctl start docker
```

Add user to docker group:

sudo usermod -aG docker $USER
# Log out and back in

Test Docker access:
```
docker ps
```

Image pull errors

Cause: Network issues or image doesn’t exist.Solutions:

Pull image manually:
```
docker pull mochoa/mcp-mysql
```
Check Docker Hub for image availability

Build image locally if needed:

docker build -t mochoa/mcp-mysql -f src/mysql/Dockerfile .

Client Configuration Issues

Claude Desktop

MCP server not appearing in Claude

Cause: Configuration syntax error or file location issue.Solutions:

Verify JSON syntax:

# Use a JSON validator
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .

Check file location:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Restart Claude Desktop after configuration changes
Check Claude logs for errors:
- macOS: ~/Library/Logs/Claude/

Environment variables not being passed

Cause: Incorrect syntax in configuration.Solution:

{
  "mcpServers": {
    "mysql": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MYSQL_USER=myuser",
        "-e", "MYSQL_PASSWORD=mypass",
        "mochoa/mcp-mysql"
      ]
    }
  }
}

Note: Use -e flag for each environment variable.

VS Code

MCP inputs not prompting

Cause: Incorrect input configuration.Solutions:

Verify input syntax:

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "mysql_user",
        "description": "MySQL username"
      }
    ]
  }
}

Reload VS Code window: Ctrl+Shift+P → “Developer: Reload Window”

MCP server not recognized

Cause: Configuration not in correct location.Solutions:

Place in User Settings (JSON) or .vscode/mcp.json

Remove mcp key when using .vscode/mcp.json:

{
  "servers": {
    "mysql": { ... }
  }
}

Debugging Tips

Enable Verbose Logging

Docker Container Logs

View real-time logs from MCP server containers:

docker logs -f <container-id>

Database Query Logs

MySQL:

SET GLOBAL general_log = 'ON';
SET GLOBAL log_output = 'TABLE';
SELECT * FROM mysql.general_log ORDER BY event_time DESC LIMIT 20;

Oracle:

ALTER SESSION SET SQL_TRACE = TRUE;

Network Traffic Analysis

Use tcpdump to inspect network traffic:

# MySQL
sudo tcpdump -i any -A 'port 3306'

# Oracle
sudo tcpdump -i any -A 'port 1521'

# MikroTik
sudo tcpdump -i any -A 'port 8728 or port 8729'

Testing Connection Manually

Oracle SQLPlus Test

sqlplus mcp_readonly/[email protected]:1521/freepdb1

MySQL Client Test

mysql -h host.docker.internal -P 3306 -u mcp_readonly -p mydb

MikroTik API Test

Use a MikroTik API testing tool or Python script:

import routeros_api

connection = routeros_api.RouterOsApiPool(
    '192.168.88.1',
    username='admin',
    password='password',
    plaintext_login=True
)
api = connection.get_api()
list_resource = api.get_resource('/interface')
print(list_resource.get())

Common Error Messages

Error	Likely Cause	Quick Fix
`ECONNREFUSED`	Service not running	Start database/router service
`ETIMEDOUT`	Firewall blocking	Check firewall rules
`Authentication failed`	Wrong credentials	Verify username/password
`Permission denied`	Insufficient privileges	Grant required permissions
`Unknown database`	Database doesn’t exist	Create database or fix name
`Table doesn't exist`	No SELECT grant	Grant SELECT permission

Performance Issues

Slow query execution

Causes:

Missing indexes
Large result sets
Network latency

Solutions:

Use EXPLAIN to analyze queries:

mysql-explain SELECT * FROM large_table WHERE column = 'value'

Add indexes:

CREATE INDEX idx_column ON large_table(column);

Limit result sets:
```
SELECT * FROM large_table LIMIT 100;
```

AWR report generation timeout

Cause: Large performance schema data or slow database.Solutions:

Increase query timeout (if supported)

Optimize Performance Schema configuration:

-- Reduce history retention
UPDATE performance_schema.setup_consumers 
SET ENABLED = 'NO' 
WHERE NAME LIKE '%history%';

Getting Help

If you encounter issues not covered in this guide:

Check the GitHub repository for similar issues
Review server-specific documentation:
Check MCP protocol documentation at modelcontextprotocol.io
Open a GitHub issue with:
- Error messages
- Configuration (redact credentials)
- Steps to reproduce
- Environment details (OS, Docker version, etc.)

Get Started

Database Servers

Infrastructure Servers

Reference Servers

Guides

Troubleshooting Guide

Connection Issues

Oracle Connection Errors

MySQL Connection Errors

MikroTik Connection Errors

Permission Errors

Oracle Permission Issues

MySQL Permission Issues

Docker Issues

Client Configuration Issues

Claude Desktop

VS Code

Debugging Tips

Enable Verbose Logging

Testing Connection Manually

Common Error Messages

Performance Issues

Getting Help

Build docs developers (and LLMs) love

Get Started

Database Servers

Infrastructure Servers

Reference Servers

Guides

​Connection Issues

​Oracle Connection Errors

​MySQL Connection Errors

​MikroTik Connection Errors

​Permission Errors

​Oracle Permission Issues

​MySQL Permission Issues

​Docker Issues

​Client Configuration Issues

​Claude Desktop

​VS Code

​Debugging Tips

​Enable Verbose Logging

​Testing Connection Manually

​Common Error Messages

​Performance Issues

​Getting Help

Build docs developers (and LLMs) love

Connection Issues

Oracle Connection Errors

MySQL Connection Errors

MikroTik Connection Errors

Permission Errors

Oracle Permission Issues

MySQL Permission Issues

Docker Issues

Client Configuration Issues

Claude Desktop

VS Code

Debugging Tips

Enable Verbose Logging

Testing Connection Manually

Common Error Messages

Performance Issues

Getting Help