OpenCart MCP Server

Query and edit your OpenCart store from Claude Code. Products, orders, customers, Journal3 modules, SEO URLs, CMS pages — 42 tools, all through natural language.

Built for store owners and developers who are tired of SSH + phpMyAdmin + admin panel clicking to get simple answers.

"Which products are low on stock?"
"Update the meta description for category 25"
"Show me today's orders over £50"
"Find the Journal3 module that contains our FAQ text and fix the typo"

It just works. You ask, Claude calls the right tool, you get the answer.

💻 Prefer the terminal? Check out opencart-cli — same OpenCart understanding, pretty tables, sparklines, AI in the shell (opencart ask "..."), interactive REPL, live order watching. pip install opencart-cli.

---

Safe by default

This matters if you’re connecting AI to a live store. Every decision here was made with that in mind.

• Read-only queries — query() only allows SELECT, SHOW, DESCRIBE, EXPLAIN
• DDL is blocked — DROP, ALTER, TRUNCATE, CREATE will never run, even through run_sql()
• SSH tunnel — database credentials stay inside the encrypted connection, never exposed
• Path traversal blocked — get_file() and write_file() reject .. in paths
• Access policy — optional OPENCART_MCP_POLICY (safe / manager / developer / all) hides write tools by role; default all keeps previous behavior. Levels below all also apply best-effort secret guardrails (block config.php / admin user tables, redact password-like settings)
• Write confirmation — Claude Code prompts you before any write tool executes
• Nothing runs on your server — no agents, no daemons, no PHP files uploaded. The server runs on your machine and connects over SSH

You can point this at a production store and not worry about it doing something stupid. For day-to-day agent use on production data, prefer OPENCART_MCP_POLICY=safe or developer (writes allowed for module work, secrets still filtered) over all.

---

What can you actually do with it?

Store owners

• “How many orders came in this week?” → instant sales summary with daily breakdown
• “What’s running low?” → stock report sorted by quantity, lowest first
• “Update the price of product 47 to 29.99” → done, one confirmation click
• “Show me the About Us page content” → full CMS page, ready to review or edit

Developers

• “Show me the schema for oc_order” → column definitions without opening phpMyAdmin
• “List all OCMOD modifications and their status” → instant audit
• “What extensions are installed?” → full list, no admin panel needed
• “Run this SELECT against the orders table” → custom SQL with safety rails

Agencies managing multiple stores

• Run dev and live as separate MCP instances in the same Claude session
• opencart_dev__get_products vs opencart_live__get_products — no confusion
• Compare stock levels, settings, or module content across environments

Journal3 users

• List, inspect, and edit J3 modules — FAQ accordions, sliders, banners, product tabs
• Read and update theme settings and skin settings per skin
• Find/replace inside module JSON — safely change text without rewriting the entire module
• J3 tools return empty results (not errors) if Journal3 isn’t installed, so the server works with any theme

---

How it compares

---

Quick start

1. Install

git clone https://github.com/chrisbray85/opencart-mcp.git
cd opencart-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

2. Configure

cp .env.example .env

Fill in your server details:

OPENCART_SSH_HOST=your-server-ip
OPENCART_SSH_USER=your-ssh-username
OPENCART_SSH_KEY=~/.ssh/id_ed25519
OPENCART_DB_USER=your_db_user
OPENCART_DB_PASS=your_db_password
OPENCART_DB_NAME=your_opencart_database
OPENCART_ROOT=/path/to/opencart
OPENCART_STORAGE=/path/to/storage

Where to find your paths:

• OPENCART_ROOT — the directory containing index.php, admin/, catalog/, system/
• OPENCART_STORAGE — check your config.php for the DIR_STORAGE value (often outside the web root on OpenCart 3.0.3.3+)

Optional extras:

OPENCART_SSH_PORT=22           # if SSH runs on a non-standard port
OPENCART_DB_HOST=localhost     # if MySQL isn't on the same host (e.g. a tunnel)
OPENCART_DB_PREFIX=oc_         # table prefix override
OPENCART_LANGUAGE_ID=1         # skip auto-detect from config_language
# OPENCART_MCP_POLICY=all      # safe | manager | developer | all (default: all)

OPENCART_MCP_POLICY controls which tools are registered:

Guardrails (when policy is not all) block paths like config.php / .env, queries against admin user/session tables, and redact password-like keys in get_settings. This is best-effort, not a hard security boundary. Any OPENCART_DB_* value you leave unset is read from the install’s config.php automatically, so on most setups the main block above is all you need.

The storefront language is auto-detected from the store’s config_language setting, so multi-language and non-English stores work without configuration — set OPENCART_LANGUAGE_ID only to force a specific one.

No SSH? Direct MySQL mode

If your host allows remote MySQL connections (or you run your own tunnel), leave OPENCART_SSH_HOST empty and set the OPENCART_DB_* values instead:

OPENCART_SSH_HOST=
OPENCART_DB_HOST=your-mysql-host
OPENCART_DB_PORT=3306
OPENCART_DB_USER=your_db_user
OPENCART_DB_PASS=your_db_password
OPENCART_DB_NAME=your_opencart_database
OPENCART_DB_PREFIX=oc_

All SQL-backed tools work identically. File and cache tools (get_file, write_file, clear_cache, refresh_modifications) refuse to run in this mode — there’s no shell to run them on, and they must never touch a local copy of the store thinking it’s production. SSH remains the recommended transport: credentials stay inside the encrypted connection.

Using DDEV for local development?

Set OPENCART_SSH_HOST=ddev and point OPENCART_ROOT at the local project directory — commands will run via ddev exec inside your container instead of SSH:

OPENCART_SSH_HOST=ddev
OPENCART_DB_USER=db
OPENCART_DB_PASS=db
OPENCART_DB_NAME=db
OPENCART_ROOT=/Users/you/Sites/your-opencart-project

Container paths (/var/www/html etc.) are auto-resolved — you only need the local project path. (DDEV support contributed by @IceDBorn — thanks!)

3. Test the connection

source .venv/bin/activate
PYTHONPATH=src python -c "
from opencart_mcp.config import Config
from opencart_mcp.db import OpenCartDB
import json

config = Config.from_env()
db = OpenCartDB(config)
result = db.run_query('SELECT COUNT(*) as product_count FROM oc_product WHERE status = 1')
print(json.dumps(result, indent=2))
db.close()
"

You should see something like [{"product_count": "42"}]. If not, check Troubleshooting.

4. Add to Claude Code

---

Example prompts

These all work out of the box. Just type them into Claude Code.

Products & stock

"Show me all products with less than 5 in stock"
"Get full details for product 123 including options and images"
"Search for products with 'wireless' in the name"
"Update the price of product 47 to 34.99"

Orders & customers

"Show me today's orders"
"Get order 5892 with line items and status history"
"Find customer [email protected] — how many orders have they placed?"
"Sales summary for the last 7 days with top sellers"

SEO & content

"List all SEO URLs containing 'sale'"
"Update the SEO URL for product 23 to 'wireless-mouse-pro'"
"Show me the FAQ page content"
"Replace 'old company name' with 'new company name' in the About Us page"

Journal3 theme

"List all Journal3 FAQ modules"
"Show me the full content of module 505"
"Replace 'Free shipping over £50' with 'Free shipping over £75' in the banner module"
"What skin settings are configured for skin 1?"

Technical

"Show the schema for oc_order_product"
"List all tables matching 'journal3'"
"Run: SELECT order_id, total FROM oc_order WHERE total > 100 ORDER BY date_added DESC LIMIT 10"
"What OCMOD modifications are active?"

---

All 42 tools

Read (27)

Write (15)

---

How it works

Your machine                          Your server
┌──────────────┐                     ┌──────────────┐
│ Claude Code  │                     │              │
│      ↓       │     SSH tunnel      │   PHP cli    │
│  MCP Server  │ ──────────────────→ │      ↓       │
│  (Python)    │   PHP via stdin     │   MySQL      │
│              │ ←────────────────── │   (JSON)     │
└──────────────┘                     └──────────────┘

The server runs on your machine. It connects to your OpenCart server via SSH, pipes PHP to the remote interpreter via stdin, and gets JSON back. Nothing is installed on your server. No files uploaded, no cleanup, no ports opened.

• PHP via stdin — works with any PHP version, nothing written to disk
• SSH tunnel — credentials never leave the encrypted connection
• Paramiko — pure Python SSH, no system dependencies beyond Python 3.10+
• Direct MySQL — pymysql fallback for hosts without SSH (file/cache tools disabled)

---

Multiple stores

Run dev and live as separate instances in the same Claude session:

{
  "mcpServers": {
    "opencart_dev": {
      "command": "/path/to/opencart-mcp/.venv/bin/python",
      "args": ["-m", "opencart_mcp.server"],
      "cwd": "/path/to/opencart-mcp",
      "env": { "OPENCART_DB_NAME": "my_dev_database", "..." }
    },
    "opencart_live": {
      "command": "/path/to/opencart-mcp/.venv/bin/python",
      "args": ["-m", "opencart_mcp.server"],
      "cwd": "/path/to/opencart-mcp",
      "env": { "OPENCART_DB_NAME": "my_live_database", "..." }
    }
  }
}

Claude prefixes tools automatically — opencart_dev__get_products vs opencart_live__get_products — so there’s no confusion about which store you’re querying.

You can also run the same store twice with different policies (e.g. daily safe plus an occasional developer entry) by duplicating the block and setting OPENCART_MCP_POLICY per instance.

---

Tested with

Used daily on production stores with 100+ products, thousands of orders, and Journal3 theme.

---

Troubleshooting

SSH connection fails

# Test SSH works
ssh your-user@your-server "echo ok"

# Test PHP is available
ssh your-user@your-server "echo '<?php echo 1;' | php"

If SSH needs a password instead of a key:

ssh-copy-id -i ~/.ssh/id_ed25519.pub your-user@your-server

Empty results

• Run the test script to check credentials
• OPENCART_ROOT should point to the directory containing index.php
• OPENCART_STORAGE should match DIR_STORAGE in your config.php

cPanel / shared hosting

cPanel prints tput: No value for $TERM warnings over SSH. The server filters these automatically.

Slow queries

Default timeout is 30 seconds. If queries are slow, check if SSH goes through a VPN (adds latency) or if the server is under load.

Journal3 tables not found

Normal if you’re not running Journal3. The J3 tools return empty results instead of errors.

Common path issues

Check your config.php — both DIR_APPLICATION and DIR_STORAGE are defined there.

---

Roadmap

• [ ] OpenCart 4.x support
• [x] Direct MySQL transport + language auto-detection (v0.7.0)
• [x] Coupon and voucher management tools (v0.6.0)
• [x] Order status update tool (v0.6.0)
• [ ] Bulk product import/export
• [ ] Customer group management
• [x] Dashboard summary tool (one prompt, full store overview) (v0.6.0)

Got a feature request? Open an issue.

---

Changelog

See releases for full history.

0.7.0

• Direct MySQL transport (pymysql) when OPENCART_SSH_HOST is empty — file/cache tools refuse in this mode
• Storefront language_id auto-detected from config_language (override with OPENCART_LANGUAGE_ID) — fixes hardcoded language_id = 1 on non-English stores
• Revenue queries now also exclude canceled-reversal, chargeback, and voided orders
• First unit tests (tests/test_config.py)

---

Contributing

Issues and PRs welcome. If you’re running this on a hosting setup or OpenCart version not listed above, let us know what works and what doesn’t.

Thanks to the contributors so far:

• @IceDBorn — DDEV support and the Nix flake
• @ClayRabbit — configurable SSH port and full config.php DB fallback
• @Penikov — direct MySQL transport and language auto-detection; maintains the livestore-mcp fork for LiveStore + Technics stores

Support

Built and maintained in evenings. If it saves you time on a store, a coffee helps keep the tools coming:

License

MIT — see LICENSE for details.