/setup-pencil.en

description: "Lesson command"
duration: "~15 min"
prerequisites: ["Browser available", "Claude Code or Cursor installed"]
level: "beginner"
tags: ["setup", "pencil", "mcp", "design"]
nonInteractiveMode: incompatible

Pencil MCP Setup

Step 0: Check Setup Progress

**What the AI auto-runs:** 1. Run `uv run python tools/setup_progress.py show --current setup-pencil` to display progress 2. Auto-detect existing settings:

• For Claude Code: Check whether a `pencil` server is defined in `~/.claude/mcp_settings.json`
• For Cursor: Check whether a `pencil` server is defined in `.cursor/mcp.json`
• If already configured, only run Step 4 (connection test) and mark as complete

What You'll Do in This Session

| Item | Details | |------|---------| | Goal | Install the Pencil desktop app and enable design file (.pen) operations from Claude Code/Cursor via the MCP server | | Duration | ~15 minutes | | Prerequisites | Browser available, Claude Code or Cursor already installed | | Skill Level | App installation + MCP configuration (AI-assisted) |

**Session flow:** 1. Download and install the Pencil desktop app 2. Launch Pencil and complete initial setup 3. Add the Pencil server to the MCP configuration file 4. MCP connection test

> **Hint**: If the AI stops responding midway, type "please continue" or "it stopped" to resume.

---

Readiness Check

**AskQuestion configuration:**

{
  "title": "Pre-session confirmation",
  "questions": [{
    "id": "readiness",
    "prompt": "Are you ready?",
    "options": [
      {"id": "ready", "label": "Ready! Let's start"},
      {"id": "check_prereq", "label": "I want to check the prerequisites"},
      {"id": "already_installed", "label": "Pencil is already installed"},
      {"id": "different_lesson", "label": "Go to a different lesson"}
    ]
  }]
}

(ready -> Proceed to Step 1) (check_prereq -> Guide: "You're good to go if Claude Code or Cursor is already installed") (already_installed -> Skip to Step 3 (MCP configuration)) (different_lesson -> Show module list)

---

Step 1: Download the Pencil Desktop App

**What the AI does:** 1. Auto-detect the OS (Mac / Windows / Linux) 2. Open the Pencil download page in the browser:

# Mac:
open https://pencil.evolves.dev/download
# Windows:
start https://pencil.evolves.dev/download
# Linux:
xdg-open https://pencil.evolves.dev/download

**Once the browser opens, display the following AskQuestion:**

{
  "title": "Step 1: Download the Pencil App",
  "questions": [{
    "id": "download_status",
    "prompt": "Did the Pencil download page open in your browser?\n\nSteps:\n1. Download the installer for your OS (Mac / Windows)\n2. Run the downloaded file to install\n   - Mac: Open the .dmg and drag to the Applications folder\n   - Windows: Run the .exe and follow the wizard\n\nWere you able to install it?",
    "options": [
      {"id": "installed", "label": "Installed!"},
      {"id": "browser_not_open", "label": "The browser didn't open"},
      {"id": "download_issue", "label": "Can't download"},
      {"id": "mac_security", "label": "I'm getting a Mac security warning"}
    ]
  }]
}

(installed -> Proceed to Step 2) (browser_not_open -> Guide: "Please open this URL directly in your browser: https://pencil.evolves.dev/download") (download_issue -> Guide: "Please check your internet connection. If the download is slow, please wait a moment") (mac_security -> Guide: "Go to System Settings -> Privacy & Security -> click 'Open Anyway'. Alternatively, right-click the app in Finder and select 'Open'")

---

Step 2: Launch and Initial Setup of the Pencil App

**Message to show the user:**

Please launch the Pencil app:

┌─────────────────────────────────────────────────────────────┐
│ 1. Launch "Pencil" from your Applications                   │
│ 2. If account creation or login is required on first        │
│    launch, follow the on-screen instructions                │
│ 3. You're good once the editor screen appears               │
│                                                             │
│ * Pencil is a desktop app for creating and editing          │
│   design files in .pen format                               │
└─────────────────────────────────────────────────────────────┘

**AskQuestion configuration:**

{
  "title": "Step 2: Launch the Pencil App",
  "questions": [{
    "id": "app_status",
    "prompt": "Were you able to launch the Pencil app?",
    "options": [
      {"id": "running", "label": "Pencil is running!"},
      {"id": "cant_find", "label": "I can't find the app"},
      {"id": "crash", "label": "It crashes on launch"},
      {"id": "login_issue", "label": "I'm having trouble with login/account creation"}
    ]
  }]
}

(running -> Proceed to Step 3) (cant_find -> Mac: Check the "Applications" folder / Windows: Check the Start Menu. If installation isn't complete, go back to Step 1) (crash -> Guide: "Make sure your OS is up to date. If the problem persists, try uninstalling and reinstalling") (login_issue -> Guide: "You can create an account on the Pencil website (https://pencil.evolves.dev). You can register with your email address")

---

Step 3: Add Pencil Server to MCP Configuration File

**What the AI auto-runs:**

1. Determine the tool being used (Claude Code or Cursor) 2. Guide the Pencil MCP server configuration

**Pencil MCP connection method:**

Pencil MCP is built into the Pencil desktop app. When the app is running, it automatically becomes available as an MCP server.

**For Claude Code:** Add the following to `~/.claude/mcp_settings.json`:

{
  "mcpServers": {
    "pencil": {
      "url": "http://localhost:13742/sse"
    }
  }
}

**For Cursor:** Add the following to `~/.cursor/mcp.json`:

{
  "mcpServers": {
    "pencil": {
      "url": "http://localhost:13742/sse"
    }
  }
}

> **Note**: If you already have an MCP configuration file, add the `pencil` entry inside `mcpServers`.