Paper MCP

🚀 Paper MCP Server

The MCP server connects to Paper's WebSocket API for canvas node operations, enabling seamless interaction with Paper's canvas features.

🚀 Quick Start

📦 Installation

1. Install dependencies:

npm install

2. Build the project:

npm run build

⚙️ Configuration

1. Copy env.example to .env:

cp env.example .env

2. Edit .env and fill in your values (or set environment variables directly):

# Required: Full cookie string from Paper website
# Get this from your browser's developer tools -> Application -> Cookies -> paper.design
# Should include all three cookies: paper-preauth-user-info, D7pPzj4phQRAjBC01, and ph_phc_...
PAPER_COOKIES=paper-preauth-user-info=...; D7pPzj4phQRAjBC01=...; ph_phc_dYB3kPJF9dv2vFhHjPmuuU5D7yQVDFtMYJQpVEXu9Ku_posthog=...

# Optional: Document ID to connect to (defaults to example ID)
# You can get document IDs from the list_user_documents tool or from Paper URLs
PAPER_DOCUMENT_ID=01KBWAZRVPXZZ1Y0EZ5FDT7ZYW

# Optional: Enable debug logging for WebSocket messages
DEBUG=false

🔑 Getting Your Cookies

1. Open Paper in your browser (https://app.paper.design)
2. Open Developer Tools (F12)
3. Go to Application → Cookies → https://app.paper.design
4. Copy the values for these cookies:
   • paper-preauth-user-info
   • D7pPzj4phQRAjBC01
   • ph_phc_dYB3kPJF9dv2vFhHjPmuuU5D7yQVDFtMYJQpVEXu9Ku_posthog
5. Format them as: cookie1=value1; cookie2=value2; cookie3=value3

🔗 Connecting to Cursor

Option 1: Using Cursor Settings (Recommended)

1. Open Cursor Settings (Ctrl+, or Cmd+,)
2. Search for "MCP" or navigate to Features → Model Context Protocol
3. Click "Add MCP Server" or "Edit Config"
4. Add the following configuration:

On Windows:

{
  "mcpServers": {
    "paper": {
      "command": "node",
      "args": ["C:\\Users\\grim\\paper-mcp\\dist\\index.js"],
      "env": {
        "PAPER_COOKIES": "your-cookie-string-here",
        "PAPER_DOCUMENT_ID": "01KBWAZRVPXZZ1Y0EZ5FDT7ZYW",
        "DEBUG": "false"
      }
    }
  }
}

On macOS/Linux:

{
  "mcpServers": {
    "paper": {
      "command": "node",
      "args": ["/path/to/paper-mcp/dist/index.js"],
      "env": {
        "PAPER_COOKIES": "your-cookie-string-here",
        "PAPER_DOCUMENT_ID": "01KBWAZRVPXZZ1Y0EZ5FDT7ZYW",
        "DEBUG": "false"
      }
    }
  }
}

5. Replace the paths and cookie values with your actual values
6. Restart Cursor

Option 2: Using MCP Config File

1. Find your Cursor MCP config file:

   • Windows: %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
   • macOS: ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
   • Linux: ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

2. Add the server configuration (same JSON as above)

3. Restart Cursor

Option 3: Using dotenv (Alternative)

If you prefer using a .env file:

1. Install dotenv-cli: npm install -g dotenv-cli
2. Update the Cursor config to use:

{
  "mcpServers": {
    "paper": {
      "command": "dotenv",
      "args": ["-e", ".env", "--", "node", "dist/index.js"],
      "cwd": "C:\\Users\\grim\\paper-mcp"
    }
  }
}

💻 Usage Examples

Once connected to Cursor, you can use the Paper tools in your conversations:

• "List my Paper documents"
• "Show me all nodes on the canvas"
• "Get details of node XYZ"
• "Create a new rectangle node at position (100, 200)"
• "Update node ABC with new properties"
• "Delete node DEF"

The server communicates via stdio using MCP JSON-RPC protocol.

🛠️ Tools

• list_user_documents: Get user's recent Paper documents
• list_nodes: List all nodes on the canvas
• get_node: Get details of a specific node
• create_node: Create a new node
• update_node: Update node properties
• delete_node: Delete a node