pi-affinity-mcp
Integrates with the running Affinity app to let agents execute JavaScript SDK scripts, read SDK documentation, render spreads or selections as JPEGs, and access the app's script library and SDK hints.
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.
pi-affinity-mcp
Lets AI agents work in Affinity by Canva: run JavaScript SDK scripts in the running app, read the SDK documentation, and render spreads back as images to check the result.
It is an MCP server that sits between your agent and the MCP server built into Affinity. It works with pi (installed as a package, together with a skill that teaches the agent how to work in Affinity), Claude Desktop, Claude Code, Cursor, Codex, mcporter and any other MCP client — over stdio, or over HTTP for a client on another machine.
Why not connect to Affinity directly
pi cannot connect at all. Affinity serves MCP over the legacy HTTP+SSE transport, which pi does not support.
Scripts never run from a one-shot connection. Affinity refuses
execute_scriptuntil the SDK preamble has been read in the same MCP session, so a client that opens a session per call can only list tools.
pi-affinity-mcp passes Affinity's tools through unchanged. It keeps one session open, reads the preamble before the first script, opens a new session when Affinity restarts (and tells the client if the app came back with different tools), and never sends a script twice: a script that outlives the timeout fails and says it may still have run.
Related MCP server: affinity-mcp-bridge
Requirements
Affinity 3 running on the same machine, with its MCP server enabled in Affinity's settings.
Node.js 22 or newer.
Install
npm install -g github:AOS-AgenticOS/pi-affinity-mcp
pi-affinity-mcp --selftest--selftest lists the tools and runs one script in the app:
tools: 11
- add_sdk_hint
- execute_script
…
execute_script isError: false
{"version":"Affinity 3.3.3.5004 MacOS (Oct 30 2026)","platform":"MacOS","documents":[]}If it fails, Affinity is closed or its MCP server is switched off.
pi
pi install git:github.com/AOS-AgenticOS/pi-affinity-mcpThe package registers the server with pi and adds the mcp-affinity skill; after a restart or /reload
the tools are available as mcp__affinity__<tool>. No mcp.json entry is needed, and the global
npm install above is not needed for pi either.
To try it for one session without installing: pi -e ./path/to/pi-affinity-mcp.
Other MCP clients
Each client runs the pi-affinity-mcp command. If a desktop app cannot find it, use the full path that
which pi-affinity-mcp prints.
Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json), mcporter, or pi's own
~/.pi/agent/mcp.json:
{
"mcpServers": {
"affinity": { "command": "pi-affinity-mcp" }
}
}Claude Code:
claude mcp add affinity -- pi-affinity-mcpCodex (~/.codex/config.toml):
[mcp_servers.affinity]
command = "pi-affinity-mcp"For agents other than pi, give them the skill too: copy skills/mcp-affinity into the agent's skills
folder (for example ~/.claude/skills/), or add SKILL.md to its instructions.
A client on another machine or in a container
Affinity only listens on its own machine. Run the bridge there over HTTP, with a token:
AFFINITY_MCP_TOKEN=$(openssl rand -hex 24) \
pi-affinity-mcp --http --host 0.0.0.0 --port 7767and point the client at it:
{
"mcpServers": {
"affinity": {
"url": "http://host.docker.internal:7767/mcp",
"headers": { "Authorization": "Bearer <token>" }
}
}
}What the agent gets
Tool | Does |
| runs JavaScript in the app and returns what it logs |
| render a spread, or the selection, as a JPEG |
| the SDK reference, served by the app |
| read and add hints shared across sessions |
| the app's script library |
| send an SDK bug report to the Affinity team |
The mcp-affinity skill teaches the agent how to use them: inspect
first, look the API up, run one script per step, check with a render. It also carries the SDK essentials
and the rules that keep the user's work safe, such as never closing a document the agent did not create.
examples/ has four scripts you can run with execute_script.
Command line
pi-affinity-mcp stdio MCP server (what MCP clients run)
pi-affinity-mcp --http streamable HTTP MCP server, default 127.0.0.1:7767/mcp
pi-affinity-mcp --selftest check that the app is reachable and scripts run
pi-affinity-mcp --dump-docs <dir> save the SDK documentation and tool schemas to <dir>Option | Meaning |
| Affinity's MCP endpoint, default |
| how long a call may take, default 60; raise it for long scripts |
| HTTP address and port, default |
| bearer token for |
| offer only these tools; calls to any other are refused |
| when told to stop (SIGTERM, SIGINT), close the documents its scripts opened |
| log protocol traffic to stderr |
Environment variables: AFFINITY_MCP_URL, AFFINITY_MCP_TIMEOUT, AFFINITY_MCP_TOKEN, AFFINITY_MCP_TOOLS.
--dump-docs reference saves the SDK documentation from your Affinity installation for offline reading.
The documentation is Canva's, so this repository does not include it, and reference/ is git-ignored.
Security
Scripts run inside Affinity with the permissions you gave scripts in Affinity's settings. When AI, file or network access is restricted there, the tools answer
NOT_ALLOWED; the bridge does not work around it.--httpon127.0.0.1needs no token; any other address requires one, and requests without it get401.GET /healthzanswers without a token, for health checks.--httprefuses (403) requests from a web page on another origin, so a site you visit cannot run scripts in Affinity through it.Some of Affinity's tools send what the agent wrote to Canva (
search_sdk_hints,add_sdk_hint,report_sdk_issue).--toolsleaves them out: the server then refuses them whatever the client asks.No telemetry, and no network traffic other than to the Affinity endpoint.
Troubleshooting
Symptom | Cause | Fix |
| Affinity closed, or its MCP server off | start Affinity, enable its MCP server |
| the client talks to Affinity directly | point the client at |
| Affinity moved to a newer MCP protocol | update pi-affinity-mcp |
| Affinity answered without its documentation | it retries once by itself; restart Affinity if it persists |
| the script took longer than the timeout | check the document, then raise |
| restricted in Affinity's settings | change the setting |
HTTP | no token / web-page origin / not a | send the token / call from an MCP client / |
Development
npm install
npm run check # build, type-check the pi extension, run the testsThe tests run against a fake Affinity server that behaves like the real one (legacy SSE transport, the
per-session preamble gate, its error answers), so they need neither a Mac nor Affinity. --selftest
covers the live app.
dist/ is committed because pi install git:… does not run a build. npm run verify:dist fails when
dist/ is out of date, and CI runs it.
Source: src/client.ts (connection to Affinity), src/bridge.ts (session, preamble, reconnects),
src/mcp.ts (MCP server, stdio), src/http.ts (HTTP transport), src/cli.ts, extensions/register.ts
(pi registration), skills/mcp-affinity (the agent skill).
License
MIT for this project's code. Affinity and its SDK documentation belong to Canva — see NOTICE.
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
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Host any HTTP API as a standard MCP server; auto-distribute to 12+ mainstream agent platforms.
MCP server to assist with JxBrowser development.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceProxies the local Affinity MCP server over stdio, enabling tools to call Affinity's tools like execute_script and search_sdk_hints via MCP.23 npm4MIT
- AlicenseAqualityCmaintenanceBridges MCP clients to Affinity by Canva's local MCP server, exposing tools for script execution, rendering, and SDK documentation.1143 npm12MIT
- AlicenseNot gradedqualityCmaintenanceConnects Codex to Affinity's native local MCP server through a local SSE-to-stdio bridge, enabling document inspection, vector and photo editing, page layout work, native previews, and reusable scripts without any cloud server or API key. It also relays the app's optional global hint-search and issue-reporting tools, and works only against the locally running app on 127.0.0.1.MIT
- AlicenseNot gradedqualityBmaintenanceEnables any MCP client to drive the real Figma Desktop plugin API through one local daemon, so agents can read and edit the open file, take screenshots, export assets, and inspect variables, components, and styles. Everything stays on 127.0.0.1 with no cloud, API keys, or Dev/Full seat required.71 npm1MIT