CSP Companion MCP
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
CSP Companion MCP
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.
Features and limits
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: Blockland MCP
Requirements
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.
Installation
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.
Pair once, locally
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.jsonwith restricted file permissions. Do not paste it into chat or a public issue.Optionally run
check_connection.pywith 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.
Configure Codex
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.
Tools
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.
Local paths
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.
Tests
.\.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.
Contributing and attribution
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.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Connect any MCP client to MetaTrader 4/5 to read prices, manage positions, and place trades.
Use your Pronto feed, Spaces, Posts, Artifacts, and agents from any MCP client.
Toolstile is a managed MCP gateway that connects remote MCP servers behind one endpoint, with per-agent permissions, shared accounts and activity logs. Connect at https://mcp.toolstile.com/mcp over Streamable HTTP with OAuth; sign in at https://toolstile.com, select a workspace and connect your upstream servers. Available tools, resources and prompts depend on that workspace and the agent's granted access.
Screenshots, PDFs, image editing, QR codes, email validation and more through one hosted MCP server.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables MCP-compatible AI clients to control a running Krita instance, allowing them to create canvases, paint strokes, draw shapes, export images, and perform other painting tasks.MIT
- AlicenseNot gradedqualityCmaintenanceEnables an MCP client to connect to a running Blockland client to execute TorqueScript, inspect player state, control character movement and actions, and capture screenshots.MIT
- AlicenseAqualityBmaintenanceExperimental Windows-first MCP server for Adobe Photoshop, with guarded brush-based painting and direct document and layer tools through a local UXP bridge. Requires local Photoshop on Windows for execution; Linux supports MCP catalog introspection only.391MIT
- AlicenseNot gradedqualityBmaintenanceEnables external AI clients to automate and inspect Pencil2D through MCP, including authenticated sessions, layers, keyframes, strokes, undo/redo, previews, saves, snapshots, and export jobs.GPL 2.0