mariadb-mcp-server

# MariaDB / MySQL MCP Server This MCP server exposes MariaDB and MySQL databases to MCP clients such as Claude Desktop, VS Code, and other compatible tools. It provides tools to: - list available databases - list tables in a database - describe table schemas - execute SQL queries ## Features - Safe-by-default behavior: read-only access is enabled by default - Query validation to block disallowed statements and reduce injection risk - Configurable write permissions through environment variables - Timeout and row-limit protection - Numeric safety for insert IDs and BIGINT values returned by the MariaDB driver ## Installation ### Option 1: Install from npm ```bash npm install -g mariadb-mcp-server ``` ### Option 2: Install locally ```bash npm install mariadb-mcp-server ``` ### Option 3: Build from source ```bash git clone https://github.com/rjsalgado/mariadb-mcp-server.git cd mariadb-mcp-server npm install npm run build ``` ## Configuration Set the following environment variables before starting the server: - `MARIADB_HOST`: Database host - `MARIADB_PORT`: Database port (default: `3306`) - `MARIADB_USER`: Database username - `MARIADB_PASSWORD`: Database password - `MARIADB_DATABASE`: Default database name (optional) - `MARIADB_ALLOW_INSERT`: Enable `INSERT` statements (`true`/`false`) - `MARIADB_ALLOW_UPDATE`: Enable `UPDATE` statements (`true`/`false`) - `MARIADB_ALLOW_DELETE`: Enable `DELETE` statements (`true`/`false`) - `MARIADB_TIMEOUT_MS`: Query timeout in milliseconds (default: `10000`) - `MARIADB_ROW_LIMIT`: Maximum number of rows returned (default: `1000`) Example: ```bash export MARIADB_HOST=localhost export MARIADB_PORT=3306 export MARIADB_USER=myuser export MARIADB_PASSWORD=mypassword export MARIADB_DATABASE=mydb export MARIADB_ALLOW_INSERT=false export MARIADB_ALLOW_UPDATE=false export MARIADB_ALLOW_DELETE=false export MARIADB_TIMEOUT_MS=10000 export MARIADB_ROW_LIMIT=1000 ``` ## MCP configuration ### Using npm package ```json { "mcpServers": { "mariadb": { "command": "npx", "args": ["mariadb-mcp-server"], "env": { "MARIADB_HOST": "your-host", "MARIADB_PORT": "3306", "MARIADB_USER": "your-user", "MARIADB_PASSWORD": "your-password", "MARIADB_DATABASE": "your-database", "MARIADB_ALLOW_INSERT": "false", "MARIADB_ALLOW_UPDATE": "false", "MARIADB_ALLOW_DELETE": "false", "MARIADB_TIMEOUT_MS": "10000", "MARIADB_ROW_LIMIT": "1000" }, "disabled": false, "autoApprove": [] } } } ``` ### Using a built local server ```json { "mcpServers": { "mariadb": { "command": "node", "args": ["/absolute/path/to/mariadb-mcp-server/dist/index.js"], "env": { "MARIADB_HOST": "your-host", "MARIADB_PORT": "3306", "MARIADB_USER": "your-user", "MARIADB_PASSWORD": "your-password", "MARIADB_DATABASE": "your-database", "MARIADB_ALLOW_INSERT": "false", "MARIADB_ALLOW_UPDATE": "false", "MARIADB_ALLOW_DELETE": "false", "MARIADB_TIMEOUT_MS": "10000", "MARIADB_ROW_LIMIT": "1000" }, "disabled": false, "autoApprove": [] } } } ``` ## Available tools The server registers the following MCP tools: ### `list_databases` Lists all databases accessible to the configured user. ### `list_tables` Lists tables from a specific database. Parameters: - `database` (optional): database name to inspect ### `describe_table` Returns the schema of a specific table. Parameters: - `database` (optional): database name - `table` (required): table name ### `execute_query` Executes a SQL query. Parameters: - `database` (optional): database name - `query` (required): SQL statement to run ## Testing The repository includes scripts to validate the server against a MariaDB or MySQL instance. ```bash npm run test:setup npm run test:tools ``` Or run everything together: ```bash npm test ``` ## Notes - The server is safe-by-default and only allows read-only operations unless the write flags are explicitly enabled. - Write operations are still subject to query validation and runtime limits. ## Troubleshooting If you encounter issues: 1. Check the server logs for error messages 2. Verify your MariaDB/MySQL credentials and connection details 3. Ensure your MariaDB/MySQL user has appropriate permissions 4. Check that your query is read-only and properly formatted **Inspiration** **https://github.com/dpflucas/mysql-mcp-server** ## License This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.