Magento SQL MCP Server

An MCP (Model Context Protocol) server that provides AI assistants with read-only access to a Magento 2 / Adobe Commerce MySQL database. It auto-detects local DDEV environments, connects to Adobe Commerce Cloud via CLI tunnels, and ships 50+ tools for orders, catalog, customers, CMS, config, indexers, and diagnostics.

Complementary MCP: Documentation MCPs (see Related MCPs) cover official Adobe Commerce docs. This package covers your live database.

Features

• 50+ read-only tools for orders, products, customers, CMS, config, EAV, MSI, B2B, staging, cron, and indexers

• Read-only by design — blocks INSERT/UPDATE/DELETE/DDL; masks password, token, and credit-card columns

• Multi-environment profiles — local DDEV, Adobe Commerce Cloud (staging/production), direct remote DB, SSH tunnel

• Zero-config local dev — reads app/etc/env.php, auto-detects DDEV MySQL port (cached 120s)

• Commerce-aware — detects staging (updated_in), MSI, B2B; EAV joins use row_id on Commerce

• CMS helpers — get_cms_page, audit_cms_page_blocks

• Parameter aliases — query to sql, path to pathPattern, entity_type to entity_type_code

• Per-call profile override — pass profile: "staging" on any tool without restarting MCP

• MCP standards — Zod schemas, structured output, tool annotations, server instructions

• Resources and prompts — table reference, EAV cheatsheet, order-debug and MSI-troubleshoot workflows

• Dual transport — stdio (default) and optional HTTP for LibreChat / remote hosts

Related MCP server: Magento MCP Server

Quick setup for Cursor

Prerequisites

Option A: npx (recommended)

1. Open Cursor → Settings → MCP → Add new MCP server

2. Configure:

3. Set environment variables:

4. Restart Cursor. Verify with: Call get_connection_status

Option B: Project config (.cursor/mcp.json)

Create in your Magento project root:

{
  "mcpServers": {
    "magento-sql": {
      "command": "npx",
      "args": ["-y", "magento-sql-mcp-server"],
      "env": {
        "MAGENTO_ROOT": "/absolute/path/to/magento",
        "MAGENTO_SQL_PROFILE": "local"
      }
    }
  }
}

Run from source (development):

{
  "mcpServers": {
    "magento-sql": {
      "command": "node",
      "args": ["/absolute/path/to/magento-sql-mcp-server/dist/index.js"],
      "env": {
        "MAGENTO_ROOT": "/absolute/path/to/magento",
        "MAGENTO_SQL_PROFILE": "local"
      }
    }
  }
}

Option C: Init profile scaffold

npx magento-sql-mcp-server --init

Creates .cursor/magento-sql-mcp.json from examples/magento-sql-mcp.example.json.

Profiles named default, local, or dev auto-fallback to DDEV/env.php detection without a config file.

Setup for other tools

Claude Desktop

Use the same mcpServers JSON as Cursor.

VS Code / GitHub Copilot

.vscode/mcp.json — same env vars; use "servers" key instead of "mcpServers".

Windsurf

~/.codeium/windsurf/mcp_config.json — same structure as Claude Desktop.

Connection profiles

Profile file

Create .cursor/magento-sql-mcp.json in your Magento project (see examples/magento-sql-mcp.example.json):

{
  "defaultProfile": "local",
  "profiles": {
    "local": { "mode": "auto" },
    "staging": {
      "mode": "direct",
      "database": {
        "host": "127.0.0.1",
        "port": 30000,
        "dbname": "your_project_stg",
        "username": "your_project_stg",
        "password": "${MAGENTO_STAGING_DB_PASSWORD}"
      }
    },
    "production": {
      "mode": "direct",
      "database": {
        "host": "127.0.0.1",
        "port": 30000,
        "dbname": "your_project_id",
        "username": "your_project_id",
        "password": "${MAGENTO_PRODUCTION_DB_PASSWORD}"
      }
    }
  }
}

Set passwords in MCP env (never commit credentials):

"env": {
  "MAGENTO_STAGING_DB_PASSWORD": "from-tunnel-info",
  "MAGENTO_PRODUCTION_DB_PASSWORD": "from-tunnel-info",
  "MAGENTO_SQL_PROFILE": "local"
}

Global shared profiles: ~/.config/magento-sql-mcp/config.json

Connection modes

Config values support ${ENV_VAR} references for secrets.

Per-tool override: pass profile on any tool call without changing MAGENTO_SQL_PROFILE.

Adobe Commerce Cloud setup

Cloud MySQL runs on database.internal:3306 inside the environment. It is not reachable from the public internet. Use an SSH tunnel (same approach as DBeaver with SSH enabled).

Laptop                    Cloud environment
127.0.0.1:30000  --SSH--> database.internal:3306

Step 1: Install and authenticate Cloud CLI

Documentation: Adobe Commerce Cloud CLI

magento-cloud login
magento-cloud auth:info
magento-cloud project:list
magento-cloud environments -p YOUR_PROJECT_ID

Non-interactive auth: magento-cloud auth:api-token-login or export MAGENTO_CLOUD_CLI_TOKEN=...

Step 2: Open tunnel

# Staging
magento-cloud tunnel:open -p YOUR_PROJECT_ID -e staging

# Production
magento-cloud tunnel:open -p YOUR_PROJECT_ID -e production

Example output:

SSH tunnel opened to database at: mysql://user:pass@127.0.0.1:30000/dbname?compression=1

Default ports (single environment open):

Note: Staging and production both use port 30000. Close the current tunnel before opening another:

magento-cloud tunnel:close
magento-cloud tunnel:open -p YOUR_PROJECT_ID -e staging

Step 3: Get credentials

magento-cloud tunnel:info -p YOUR_PROJECT_ID -e staging
magento-cloud tunnel:info -P database

On the remote container (SSH):

echo $MAGENTO_CLOUD_RELATIONSHIPS | base64 -d | json_pp

CLI reference: Cloud CLI reference

Step 4: Configure MCP profiles

Cloud profiles use direct mode to 127.0.0.1:30000. The tunnel must remain open while MCP is connected.

Add .cursor/mcp.json and .cursor/magento-sql-mcp.json to .gitignore.

Step 5: Switch environments

Step 6: Verify connection

magento-cloud tunnels

MCP tools:

• get_connection_status (with profile: "staging" or "production")

• detect_magento_environment

magento-cloud url -p YOUR_PROJECT_ID -e staging

Step 7: Close tunnel

magento-cloud tunnel:close

Cloud config URLs vs storefront URLs

core_config_data base URLs (web/unsecure/base_url, web/secure/base_url) on staging often still show the production domain (DB cloned from production). Actual storefront URLs are set by Cloud routes and Fastly.

Timezone-aware order queries

Store timezone: general/locale/timezone in core_config_data. Order created_at is stored in UTC. Convert store-local date ranges to UTC before querying sales_order. Use get_magento_config with pathPattern: "general/locale/%" to read the timezone.

Tools

Call list_available_tools for the full catalog with edition tags (OSS / MSI / B2B / Commerce).

Connection and environment

SQL and schema

Catalog and products

Sales and customers

Operations, CMS, and config

Edition-specific tools return a clear error if required tables are missing.

Resources

Prompts

Usage examples

How it works

+-------------+     +---------------------------+     +-----------------------------+
|  AI Client  |---->|  MCP Server (stdio/HTTP)  |---->|  MySQL (read-only)          |
|  Cursor,    |<----|  50+ Tools                |<----|  Magento / Adobe Commerce   |
|  Claude,    |     |  7 Resources, 9 Prompts   |     +-----------------------------+
|  VS Code    |     +---------------------------+
+-------------+
                      |
                      +-- Profile: MAGENTO_SQL_PROFILE -> config JSON
                      +-- auto mode: env.php + DDEV port (cached 120s)
                      +-- Cloud: magento-cloud tunnel -> 127.0.0.1:30000
                      +-- Query validation: read-only only
                      +-- Auto LIMIT 100 (max 1000)
                      +-- Sensitive column masking
                      +-- Commerce staging: updated_in = 2147483647

1. MCP host starts the server with MAGENTO_ROOT pointing at your Magento project

2. resolveConnection() loads profile from .cursor/magento-sql-mcp.json or auto-detects

3. For local DDEV: reads app/etc/env.php, runs ddev describe -j once (cached)

4. Tools run validated read-only SQL or canned queries with Magento-aware joins

5. Results return as structured JSON with Zod schemas

HTTP transport

npx magento-sql-mcp-server --http
# listens on http://localhost:3100 (override with MCP_HTTP_PORT)

LibreChat librechat.yaml:

mcpServers:
  magento-sql:
    type: streamable-http
    url: http://localhost:3100
    initTimeout: 30000

Configuration

Environment variables

Per-tool overrides: magentoRoot and profile arguments on most tools.

Troubleshooting

MCP server failed to start

• Verify Node.js 18+: node --version

• Test manually: npx magento-sql-mcp-server (should print "running on stdio")

• Ensure MAGENTO_ROOT points to a directory with app/etc/env.php

Profile local not found

v2.4.0+ auto-fallbacks local/default/dev to auto-detect. Upgrade or run:

npx magento-sql-mcp-server --init

Connection refused on Cloud (port 30000)

• Tunnel not running: magento-cloud tunnel:open -p PROJECT_ID -e staging

• Wrong environment: magento-cloud tunnels then close and reopen

• Tunnel dropped after reboot: re-run tunnel:open

Connected to wrong environment

Run get_connection_status and check database. Staging names often end in _stg; production matches project ID.

Missing password environment variable

Copy password from magento-cloud tunnel:info into MCP env. Do not commit it.

DDEV connection refused / wrong port

• Ensure DDEV is running: ddev start

• DDEV port is cached for 120s after first discovery

Tool parameter errors

Slow queue / health check tools

On large databases, queue backlog uses sampled counts. Check sampled: true in results.

Green dot does not appear in Cursor

• Restart Cursor

• Refresh MCP server in settings

• Check Output panel for errors

Security

• All queries validated as read-only before execution

• Auto LIMIT (default 100, max 1000) on SELECT without explicit LIMIT

• Password, token, and credit-card columns masked in results

• Customer/admin password hashes never exposed

• Use read-only MySQL users for Cloud profiles when available

• Never commit credentials; use MCP env or ${ENV_VAR} in config JSON

• Close Cloud tunnels when finished; avoid heavy full-table scans on production

Development

Run from source

git clone https://github.com/jigarkkarangiya/magento-sql-mcp-server.git
cd magento-sql-mcp-server
npm install
npm run build
MAGENTO_ROOT=/path/to/magento npm start

Tests

npm test
MAGENTO_ROOT=/path/to/magento npm run test:live
MAGENTO_ROOT=/path/to/magento npm run test:scenarios

Project structure

magento-sql-mcp-server/
├── src/                 # MCP server source
├── scripts/             # live-tool-smoke.ts, scenario-benchmark.ts
├── tests/               # unit tests
├── examples/            # magento-sql-mcp.example.json
└── dist/                # compiled JS (npm run build)

Requirements

Find this MCP

Related MCPs

Documentation MCPs for Adobe Commerce and related platforms. Install alongside this server for docs + database coverage.

Combined Cursor config:

{
  "mcpServers": {
    "magento-sql": {
      "command": "npx",
      "args": ["-y", "magento-sql-mcp-server"],
      "env": {
        "MAGENTO_ROOT": "/absolute/path/to/magento",
        "MAGENTO_SQL_PROFILE": "local"
      }
    },
    "adobe-commerce-docs": {
      "command": "npx",
      "args": ["-y", "adobe-commerce-docs-mcp"]
    },
    "adobe-commerce-dev-docs": {
      "command": "npx",
      "args": ["-y", "adobe-commerce-dev-docs-mcp"]
    },
    "adobe-commerce-kb": {
      "command": "npx",
      "args": ["-y", "adobe-commerce-kb-mcp"]
    }
  }
}

All MCP packages: github.com/jigarkkarangiya?tab=repositories&q=mcp