Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@CSP Companion MCP Connect to CSP, then list the Quick Access items you can run."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An experimental, unofficial MCP server for CLIP STUDIO PAINT's Companion protocol. Connect an MCP client to CSP over local TCP, without desktop input automation or desktop screenshots.
Connect and disconnect after manual Companion pairing.
List Quick Access items and execute enabled, locally allowlisted items.
Read synchronized brush state; request color, brush size and opacity changes.
Request canvas zoom, rotation and flipping.
Retrieve composite canvas previews exposed by the Companion protocol.
This is not a general layer API. It cannot enumerate layers, edit layer pixels, split artwork into layers, paint strokes, or target documents by a stable document ID. Commands affect CSP's currently active document.
Validation: authentication, Quick Access listing and reconnecting were verified against CSP 5.1.4 on Windows. Mutation, navigation and preview features have mock coverage but have not been verified against real CSP. Protocol acknowledgement alone does not prove the canvas changed. See VALIDATION.md.
Related MCP server: Krita MCP Server
Windows (the platform used for live validation).
Python 3.11 or newer and the dependencies in requirements.txt.
CLIP STUDIO PAINT with Companion mode available and enabled.
A client supporting MCP over stdio, such as Codex.
Other operating systems have not been validated.
Clone this repository and open PowerShell in its directory:
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txtYou may use a newer supported Python interpreter. The server and virtual environment can be stored on any drive.
In CSP, open File > Connect to smartphone to enable Companion mode.
Obtain the complete pairing URL from CSP's QR code, for example by scanning it with your phone and copying the URL to your own computer.
In an interactive PowerShell terminal, run:
.\.venv\Scripts\python.exe setup_pairing.pyPaste the URL into the hidden prompt. The script saves session.json with
restricted file permissions. Do not paste it into chat or a public issue.
Optionally run check_connection.py with the same interpreter. It connects
and disconnects without executing canvas commands. Do not run it while
another Companion client is connected.
Only loopback and this computer's own IPv4 addresses are accepted. CSP rotates
the connection password; reconnecting uses the locally saved credentials.
If pairing expires, privately back up session.json and pair again. The
setup script will not overwrite an existing pairing file.
Add a server entry to your Codex MCP configuration, substituting your actual absolute paths (the examples below are placeholders):
[mcp_servers.csp-companion]
command = 'F:\Projects\csp-companion-mcp\.venv\Scripts\python.exe'
args = ['-u', 'F:\Projects\csp-companion-mcp\server.py']
[mcp_servers.csp-companion.env]
PYTHONUTF8 = '1'
CSP_COMPANION_OUTPUT = 'F:\CSPoutput\CompanionPreviews'Restart or refresh your MCP client. First call csp_status, then
csp_connect, then csp_quick_access_list. Execute changes only when the
user requests them. Never retry a mutation automatically after a timeout;
the operation may already have reached CSP.
Other stdio MCP clients can use the same Python executable and server script.
Tool | Purpose |
| Read connection and capability status |
| Manage the Companion connection |
| List actual Quick Access items and allowlist status |
| Execute one enabled, allowlisted item |
| Read received brush synchronization fields |
| Request an RGB color change |
| Request brush size and/or opacity changes |
| Request canvas view changes |
| Read available composite preview metadata |
| Save a bounded composite preview block as PNG |
The default policy.json only allows Quick Access basiccommand entries
named undo and redo; allowed tool UUIDs start empty. Items must also be
present and enabled in CSP. No command runs automatically. Add allowlist
entries only using identifiers actually returned by CSP.
Variable | Default |
|
|
|
|
|
|
setup_pairing.py and check_connection.py use session.json beside their
scripts. If you override the server configuration path, securely relocate the
pairing file yourself and preserve its permissions.
Previews stay on the local filesystem; content returned to your MCP client is handled under that client's data policies. Never commit credentials or artwork.
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
.\.venv\Scripts\python.exe smoke_mcp.pyThese tests use simulated CSP responses and a real stdio MCP handshake. They do not connect to CSP or modify artwork. Generated files go to ignored test directories.
Bug reports and contributions are welcome. Include Python/CSP versions and reproduction steps, but remove pairing URLs, credentials and private artwork. Describe whether a result came from mock tests or real CSP.
This project was developed with AI assistance. It is an independent project, not an official CELSYS or OpenAI integration.
Protocol references: clipremote (MIT) and LumaPaletteCSP protocol notes. See THIRD_PARTY_NOTICES.md for attribution and scope.
Licensed under MIT. CLIP STUDIO PAINT belongs to CELSYS.
This server cannot be deployed
Connect any MCP client to MetaTrader 4/5 to read prices, manage positions, and place trades.
Drive WhatsApp from any MCP client: pair devices, send text and media, manage contacts and groups.
Remote MCP server for AI.TV creators — delegate account operations to your AI agent over MCP.
Securely control paired computers with ReMCP.
