OpenCart MCP Server

Query and edit your OpenCart store from Claude Code. Products, orders, customers, Journal3 modules, SEO URLs, CMS pages — 36 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

• 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.

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 .

Run it directly, no clone:

nix run github:chrisbray85/opencart-mcp

Install via a flake input (NixOS / home-manager) — adds the opencart-mcp binary to PATH:

{
  inputs.opencart-mcp.url = "github:chrisbray85/opencart-mcp";

  # then, in your NixOS configuration (configuration.nix / a module):
  environment.systemPackages = [
    inputs.opencart-mcp.packages.${pkgs.system}.default
  ];

  # …or home-manager:
  home.packages = [
    inputs.opencart-mcp.packages.${pkgs.system}.default
  ];
}

Dev shell with all deps (skip the venv steps above):

nix develop

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+)

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

Open your VS Code settings JSON (Cmd+Shift+P → "Open User Settings (JSON)") and add:

{
  "claude.mcpServers": {
    "opencart": {
      "command": "/absolute/path/to/opencart-mcp/.venv/bin/python",
      "args": ["-m", "opencart_mcp.server"],
      "cwd": "/absolute/path/to/opencart-mcp",
      "env": {
        "PYTHONPATH": "/absolute/path/to/opencart-mcp/src",
        "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"
      }
    }
  }
}

Restart VS Code and the tools will appear in the Claude Code panel.

Add to ~/.claude.json (global) or .claude/settings.json (project-level):

{
  "mcpServers": {
    "opencart": {
      "command": "/absolute/path/to/opencart-mcp/.venv/bin/python",
      "args": ["-m", "opencart_mcp.server"],
      "cwd": "/absolute/path/to/opencart-mcp",
      "env": {
        "PYTHONPATH": "/absolute/path/to/opencart-mcp/src",
        "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"
      }
    }
  }
}

Restart Claude Code and the tools load automatically.

JetBrains uses the same ~/.claude.json configuration as the CLI. Follow the CLI instructions above and restart your IDE.

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 john@example.com — 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 36 tools

Read (24)

Write (12)

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+

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.

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

• Coupon and voucher management tools

• Order status update tool

• Bulk product import/export

• Customer group management

• Dashboard summary tool (one prompt, full store overview)

Got a feature request? Open an issue.

Changelog

See releases for full history.

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.

License

MIT — see LICENSE for details.