Affinitymcp

🚀 AffinityMCP

The Universal MCP Server (Rust) offers tools for Canva workflows and automation of Affinity Photo/Designer/Publisher. It is designed for natural language use in MCP-compatible clients.

✨ Features

• 🎨 Natural Language Control: Control Affinity applications using natural language commands.
• 🖼️ File Operations: Open files, create new documents, and export in various formats.
• ⚡ 16-Parallel Processing: Process up to 16 files simultaneously for maximum efficiency.
• 🔧 Advanced Tools: Apply filters, get document info, and more.
• 🚀 Easy Setup: Simple setup for beginners with comprehensive documentation.
• 🌐 Cross-Platform Ready: Currently supports macOS (AppleScript), with Windows support planned.

🚀 Quick Start

For beginners, refer to SETUP_GUIDE.md for detailed step-by-step instructions.

Quick installation:

# Build
cargo build --release
cp target/release/affinity-mcp dist/

# Use with Cursor
# Add to Cursor MCP settings:
{
  "mcpServers": {
    "affinity-mcp": {
      "command": "npx",
      "args": ["affinity-mcp"],
      "autoStart": true
    }
  }
}

📦 Installation

Prerequisites

• Node.js 18+ (for the thin npx wrapper).
• Rust 1.76+ / Cargo (for local builds).
• Set AFFINITY_MCP_API_KEY if using Canva Connect/MCP endpoints.

Get an API key

• If your tools require Canva APIs, obtain credentials from the Canva developer console or MCP server guidance. Otherwise, you can skip this step.

Build locally

cd /path/to/affinity-mcp
cargo build --release
# copy target/release/affinity-mcp -> ./dist/
cp target/release/affinity-mcp dist/

Setup: Claude Code (CLI)

Use this one-liner (replace with your real values):

claude mcp add AffinityMCP -s user -e AFFINITY_MCP_API_KEY="sk-your-real-key" -- npx affinity-mcp

To remove:

claude mcp remove AffinityMCP

Setup: Cursor (Do not commit .cursor/mcp.json here)

Create the config in your client:

{
  "mcpServers": {
    "affinity-mcp": {
      "command": "npx",
      "args": ["affinity-mcp"],
      "env": { "AFFINITY_MCP_API_KEY": "sk-your-real-key" },
      "autoStart": true
    }
  }
}

Other Clients and Agents

Setup: Codex (TOML)

Example (Serena):

[mcp_servers.serena]
command = "uvx"
args = ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex"]

This server (minimal):

[mcp_servers.affinity-mcp]
command = "npx"
args = ["affinity-mcp"]

# Optional environment variables:
# AFFINITY_MCP_API_KEY = "sk-your-real-key"
# MCP_NAME = "affinity-mcp"

Configuration (Env)

• AFFINITY_MCP_API_KEY: Canva API key or token (if applicable).
• MCP_NAME: Server name override (default: affinity-mcp).

If your tools are purely local, no API keys are required.

💻 Usage Examples

Natural Language Commands

In Cursor or other MCP-compatible clients, you can use natural language: Example 1: Open a file

User: "Open /Users/john/Desktop/image.jpg in Affinity Photo"
AI: [Calls affinity.open_file with path="/Users/john/Desktop/image.jpg", app="Photo"]

Example 2: Create and export

User: "Create a new Affinity Photo document with size 1920x1080, then export it as PDF to my Desktop"
AI: [Calls affinity.create_new, then affinity.export]

Example 3: Get document info

User: "What document is currently open?"
AI: [Calls affinity.get_active_document]

Example 4: Batch operations (16-parallel)

User: "Open these 5 images simultaneously: /path/to/img1.jpg, /path/to/img2.jpg, /path/to/img3.jpg, /path/to/img4.jpg, /path/to/img5.jpg"
AI: [Calls affinity.batch_open_files with paths array]

Example 5: Batch export (16-parallel)

User: "Export all open documents as PDF files to the Desktop"
AI: [Calls affinity.batch_export with multiple export configurations]

Direct Tool Invocation (MCP tool call)

{
  "type": "tool",
  "name": "affinity.open_file",
  "arguments": {
    "path": "/path/to/image.jpg",
    "app": "Photo"
  }
}

📚 Documentation

• SETUP_GUIDE.md: Beginner-friendly setup guide with step-by-step instructions.
• SPEC.md: Technical specification (Japanese).
• README.md: This file (English documentation).

For complex schemas, see src/tools/*.rs.

Name Consistency & Troubleshooting

Always use CANONICAL_ID (affinity-mcp) for identifiers and keys. Use CANONICAL_DISPLAY (AffinityMCP) only for UI labels. Do not mix legacy keys after registration.

Consistency Matrix

Conflict Cleanup

Remove stale keys and re-add with affinity-mcp only. Cursor is UI-configured only; this repo intentionally omits .cursor/mcp.json.