/ docs
Open App

Cursor Setup

Set up the ASCII Motion MCP server with Cursor for AI-powered ASCII art creation.

Prerequisites

Installation

Step 1: Install the MCP Server

bash
npm install -g ascii-motion-mcp

Verify installation:

bash
ascii-motion-mcp --help

Step 2: Configure Cursor

  1. Open Cursor Settings (Cmd+, on macOS or Ctrl+, on Windows/Linux)
  2. Search for "MCP" in the settings search bar
  3. Click "Edit in settings.json"

Add the ASCII Motion MCP server with live mode enabled:

json
{
  "mcp.servers": {
    "ascii-motion": {
      "command": "ascii-motion-mcp",
      "args": ["--live", "--project-dir", "/path/to/your/projects"]
    }
  }
}
Live Mode Required

The --live flag enables real-time sync with the ASCII Motion browser editor. Without it, the MCP tools have no visual output.

Project Directory

Replace /path/to/your/projects with your actual project directory:

  • macOS: /Users/yourname/ascii-projects
  • Windows: C:\\Users\\yourname\\ascii-projects
  • Linux: /home/yourname/ascii-projects

Step 3: Restart Cursor

Close and reopen Cursor for the configuration to take effect.

Step 4: Verify Installation

Open Cursor's AI chat (Cmd+L or Ctrl+L) and ask:

"What ASCII Motion tools are available?"

You should see a list of available tools.

Using ASCII Motion with Cursor

In AI Chat

Open the AI chat panel and use natural language:

"Create a 30x20 canvas with a pixel art space invader"

Cursor will use the MCP tools to create the art.

With Composer

Use Cursor's Composer for multi-step workflows:

"Create an 8-frame animation of a walking character. Export each frame as separate PNG files, then create a combined GIF."

Inline Edits

When editing files, use Cmd+K (Ctrl+K) for inline AI:

typescript
// Create ASCII art logo
// @cursor Generate ASCII art that says "ACME" and store in this constant
const LOGO = ``;

Connect the Browser

The MCP server works with the ASCII Motion browser editor for real-time visual feedback.

Step 1: Get the Auth Token

After restarting Cursor, ask the AI:

"What is the MCP auth token?"

The AI will return a token like abc123def456.

Step 2: Open ASCII Motion

  1. Go to ascii-motion.app
  2. Click the hamburger menu (☰) in the top-left corner
  3. Select MCP Connection
  4. Paste the auth token into the input field
  5. Click Connect

You should see a green "Connected" status. Now every edit the AI makes appears instantly in the browser!

Example Prompts

Create Art

"Create a 40x25 canvas and draw an ASCII art castle with a flag on top"

Import Images

"Import the image at ./logo.png and convert it to ASCII using the standard character palette"

Animate

"Create a 6-frame animation of a spinning loading indicator using block characters"

Apply Effects

"Add a digital rain effect with varying shades of green"

Export

"Export the current project as a self-contained HTML file"

Multi-step Workflow

"Create a project with:

  1. A 50x20 canvas
  2. ASCII art text saying 'GAME OVER' in red
  3. A fade animation over 10 frames
  4. Export as GIF and React component"

Troubleshooting

MCP tools not appearing

  1. Check that settings.json is valid JSON (no trailing commas)
  2. Verify Node.js is installed: node --version
  3. Try using the full path to npx:
json
{
  "mcp.servers": {
    "ascii-motion": {
      "command": "/usr/local/bin/npx",
      "args": ["ascii-motion-mcp", "--project-dir", "/path/to/projects"]
    }
  }
}

"ENOENT" or path errors

Create the project directory first:

bash
mkdir -p /path/to/your/projects

Tools timeout or hang

The first run may take longer as npx downloads the package. Try installing globally first:

bash
npm install -g ascii-motion-mcp

Then use the direct command:

json
{
  "mcp.servers": {
    "ascii-motion": {
      "command": "ascii-motion-mcp",
      "args": ["--project-dir", "/path/to/projects"]
    }
  }
}

Connection issues with live mode

  • Check that port 9876 is available
  • Try a different port: "--port", "9877"
  • Ensure localhost connections are allowed through your firewall

Next Steps