@kaedemr/aisql

An MCP server for AI-driven CRUD operations on MySQL/MariaDB.

Features

• Run instantly with npx @kaedemr/aisql — no cloning required
• Connection info passed via environment variables — no config files needed
• Access mode control: ro (read-only) / write (read-write)
• All responses in TOON format (token-optimized for LLMs)
• Parameterized queries to prevent SQL injection
• Filesystem-access SQL (OUTFILE/DUMPFILE/LOAD_FILE/LOAD DATA) blocked in every mode
• WHERE clause validation (rejects stacked statements and comments)
• DB driver errors sanitized before reaching the LLM (schema details kept server-side only)
• No network listener: stdio transport only — nothing is exposed remotely
• Docker container health check via execFileSync (no shell interpolation)

Security Model

Read this before connecting a real database.

• The server has no network listener. It speaks MCP over stdio only, so it cannot be reached remotely. The published npm package is just code — it contains no credentials and cannot reach your DB.
• Your data still leaves the process through the LLM. Query results, DDL and schema are forwarded by your MCP client (Copilot/Claude/etc.) to the LLM provider's cloud. This is inherent to letting an AI read your DB — not specific to this server.
• Recommendations for safe use:
  • Do not use DB_USER=root. Create a least-privilege user (see below). The server prints a warning if you use root.
  • For ro, grant only SELECT and no FILE privilege so the app-layer guard is backed by DB-level enforcement.
  • Prefer local / staging / masked data. Avoid connecting production databases that hold personal data.
  • Filesystem-access SQL is blocked at the query-execution layer regardless of mode, but DB-level privilege separation is your strongest guarantee.

Recommended least-privilege users

-- Read-only user (use with DB_ACCESS_MODE=ro)
CREATE USER 'aisql_ro'@'%' IDENTIFIED BY '<strong-password>';
GRANT SELECT ON `myapp`.* TO 'aisql_ro'@'%';
-- Do NOT grant FILE. Verify it is absent:
SHOW GRANTS FOR 'aisql_ro'@'%';

-- Write user (use with DB_ACCESS_MODE=write) — scope to the target DB only
CREATE USER 'aisql_rw'@'%' IDENTIFIED BY '<strong-password>';
GRANT SELECT, INSERT, UPDATE, DELETE ON `myapp`.* TO 'aisql_rw'@'%';

Quick Start

npx @kaedemr/aisql

Global Install

npm install -g @kaedemr/aisql

Environment Variables

| Variable | Required | Default | Description | | ---------------- | -------- | ----------- | ------------------------------------ | | DB_NAME | ✅ | - | Database name | | DB_USER | ✅ | - | Database user | | DB_PASSWORD | ✅ | - | Password | | DB_HOST | - | 127.0.0.1 | Host | | DB_PORT | - | 3306 | Port | | DB_CONTAINER | - | - | Docker container name (health check) | | DB_ACCESS_MODE | - | ro | ro or write |

Available Tools

Always available (ro / write)

| Tool | Description | | ---------------- | ------------------------ | | list_tables | List all tables | | describe_table | Get table schema | | select | Execute SELECT queries |

Write mode only

| Tool | Description | | --------- | ------------------------------------ | | insert | Insert records | | update | Update records (WHERE required) | | delete | Delete records (WHERE required) | | execute | Execute arbitrary SQL (including DDL)|

Note: The where parameter in update and delete is interpolated directly into the SQL string. Always use whereParams for user-supplied values to prevent SQL injection. Example: where: "id = ?", whereParams: [42].

Development Setup

npm install
npm run build

MCP Configuration

Just add the connection info to the env block.

VS Code / Copilot (~/.vscode/mcp.json)

{
  "servers": {
    "my-db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@kaedemr/aisql"],
      "env": {
        "DB_CONTAINER": "mysql-container",
        "DB_HOST": "127.0.0.1",
        "DB_PORT": "3306",
        "DB_NAME": "myapp",
        "DB_USER": "aisql_ro",
        "DB_PASSWORD": "<your-db-password>",
        "DB_ACCESS_MODE": "ro"
      }
    }
  }
}

Claude Desktop / Claude Code

{
  "mcpServers": {
    "my-db": {
      "command": "npx",
      "args": ["-y", "@kaedemr/aisql"],
      "env": {
        "DB_HOST": "127.0.0.1",
        "DB_PORT": "3306",
        "DB_NAME": "myapp",
        "DB_USER": "aisql_rw",
        "DB_PASSWORD": "<your-db-password>",
        "DB_ACCESS_MODE": "write"
      }
    }
  }
}

Response Examples (TOON format)

list_tables

tables[3]: users,orders,products
count: 3

select

count: 2
rows[2]{id,name,age}:
  1,Alice,30
  2,Bob,25

insert

insertId: 42
affectedRows: 1

Error

error: INSERT is not allowed in read-only mode