Sylius Admin: Installation

Install the Sylius Admin Claude Code plugin: add the marketplace, enable the plugin, run the setup skill, enter credentials, verify the servers, manual installation without the plugin system, and uninstall.

Deutsche Version

Back to overview

Sylius Admin: Installation

This documentation always describes the latest published version.

Requirements

Requirement	Notes
Claude Code	With plugin (marketplace) support
Python	3.12 or newer (`requires-python = ">=3.12"`)
Sylius	2.2 with a reachable Admin API (`/api/v2/admin/`)
Admin user	A dedicated Sylius admin user for the API, see Configuration

The Python dependencies (mcp, httpx, python-dotenv, anyio) are installed by the setup skill from the plugin's requirements.txt.

Installation

As a Claude Code plugin (recommended)

Add the marketplace: claude plugin marketplace add markus-michalski/claude-plugin-syliusadmin
Enable the plugin syliusadmin from that marketplace.
Run the setup skill: /syliusadmin:setup
Enter your credentials in both .env files (see below and Configuration).
Restart Claude Code.

The setup skill performs these steps:

Step	Result
Find Python	Tries `python3`, `python` and `py -3`, and on Windows also known install locations
Check version	Python 3.12 or newer
Create venv	`~/.claude-plugin-syliusadmin/venv` (Windows: `%USERPROFILE%\.claude-plugin-syliusadmin\venv`)
Install dependencies	`pip install -r requirements.txt` from the plugin directory
Create `.env` files	`~/.claude-plugin-syliusadmin/stage/.env` and `~/.claude-plugin-syliusadmin/prod/.env`, each from `.env.example`; in the prod file `SYLIUS_ENVIRONMENT=prod` is set
Check layout	Server module importable, `bin/run-server` and both `.env` files present

The skill never fills in credentials for you, it only creates the files. It runs again on every call and also corrects a mislabeled prod/.env, so it doubles as the repair route.

After setup the plugin registers two MCP servers:

Server	Environment	Configuration file
`syliusadmin-stage-mcp`	Stage	`~/.claude-plugin-syliusadmin/stage/.env`
`syliusadmin-prod-mcp`	Prod	`~/.claude-plugin-syliusadmin/prod/.env`

Right after installation syliusadmin-prod-mcp shows failed. That is expected: prod/.env does not contain real credentials yet. Only after filling it in and restarting does the prod server become connected.

The launcher bin/run-server calls the Python interpreter from ~/.claude-mcp-syliusadmin/venv (Windows: %USERPROFILE%\.claude-mcp-syliusadmin\venv), while the setup skill creates the venv under ~/.claude-plugin-syliusadmin/venv. If both servers stay failed although the .env files are filled in, the venv is missing at the path the launcher expects. Create it there with the same dependencies, see Troubleshooting.

Manually without the plugin system

This route skips the plugin system. You then get no skills (setup, product wizard); the MCP server itself works the same.

mkdir -p ~/.claude/mcp-servers/syliusadmin-stage
cp -r servers/syliusadmin-server/src servers/syliusadmin-server/run.py requirements.txt \
  ~/.claude/mcp-servers/syliusadmin-stage/
cp .env ~/.claude/mcp-servers/syliusadmin-stage/.env
cd ~/.claude/mcp-servers/syliusadmin-stage && python3 -m venv venv && ./venv/bin/pip install -r requirements.txt

claude mcp add --scope user --transport stdio syliusadmin-stage -- \
  ~/.claude/mcp-servers/syliusadmin-stage/venv/bin/python3 \
  ~/.claude/mcp-servers/syliusadmin-stage/run.py

For prod, repeat the steps in a separate directory (for example ~/.claude/mcp-servers/syliusadmin-prod/) with SYLIUS_ENVIRONMENT=prod and the prod credentials.

Without SYLIUS_ENV_NAME and SYLIUS_ENV_FILE, run.py reads the .env right next to itself.

For development

To run the tests a venv in the project folder is enough, no MCP operation is needed:

python3 -m venv venv
./venv/bin/pip install -r requirements-dev.txt
cp .env.example .env
./venv/bin/python3 -m pytest

Verify the installation

Open /mcp in Claude Code: syliusadmin-stage-mcp must be connected.
Have a read-only tool called, for example: "List the channels of the shop." This calls list_channels.
If the tool answers with the channel codes, login and connection are fine.

Credentials and restart

After entering the credentials, Claude Code reloads the MCP servers on its next start. run.py reads the .env on every start, and the file wins over SYLIUS_* variables already set in the process.

Uninstall

Disable or remove the plugin in Claude Code. This removes both MCP servers and the skills.
Delete the folder ~/.claude-plugin-syliusadmin/ (Windows: %USERPROFILE%\.claude-plugin-syliusadmin). It contains the venv and both .env files with your credentials.
If present, delete the venv at the launcher path ~/.claude-mcp-syliusadmin/.
For a manual installation: run claude mcp remove --scope user syliusadmin-stage (and syliusadmin-prod) and delete the directory under ~/.claude/mcp-servers/.
Optional: delete or lock the Sylius admin user for the API in the shop.

Nothing is left behind on the Sylius shop itself, the server installs nothing there.

Migrating from a manual deployment

If the server used to run as a git clone under ~/.claude/mcp-servers/syliusadmin-stage, proceed like this:

Back up the contents of the old .env files.
Install the plugin and run /syliusadmin:setup.
Enter the saved credentials in the new .env files under ~/.claude-plugin-syliusadmin/.
Remove the old registration, otherwise the same environment exists twice: claude mcp remove --scope user syliusadmin-stage (and -prod).
Delete the old checkout folder and do not run git pull there, because run.py in the repo now lives under servers/syliusadmin-server/.