/ docs
Open App

Windsurf Setup

Set up the ASCII Motion MCP server with Windsurf 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 Windsurf

Open Windsurf's MCP configuration file. The location depends on your operating system:

macOS:

bash
code ~/.windsurf/mcp-config.json

Windows:

text
%USERPROFILE%\.windsurf\mcp-config.json

Linux:

bash
code ~/.config/windsurf/mcp-config.json

Add the ASCII Motion MCP server with live mode enabled:

json
{
  "mcpServers": {
    "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.

Step 3: Restart Windsurf

Close and reopen Windsurf for the configuration to take effect.

Step 4: Verify Installation

Open Windsurf's AI chat and ask:

"What ASCII Motion tools are available?"

You should see a list of available tools.

Using ASCII Motion with Windsurf

In AI Chat

Use natural language prompts:

"Create a 40x20 canvas with ASCII art of a robot"

With Cascade

Windsurf's Cascade feature works great for multi-step art creation:

"I want to create an animated logo. First, set up a 60x15 canvas. Then, use ASCII Type to write 'WELCOME' in a large font. Finally, create a color cycling animation over 8 frames."

Inline Assistance

When editing code, ask for ASCII art to embed:

"Generate ASCII art for a loading spinner that I can use in my CLI app"

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 Windsurf, ask:

"What is the MCP auth token?"

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 edits appear in real-time!

Example Prompts

Create Art

"Create ASCII art of a sailboat on water using minimal characters"

Import and Convert

"Import my-image.jpg and convert to ASCII with the retro-8bit color palette"

Animate

"Create a wave animation with 12 frames using block characters"

Export

"Export as an HTML file with a dark background"

CLI Components

"Export as a Bubbletea component for my Go terminal app"

Troubleshooting

Tools not appearing

  1. Verify the config file exists and is valid JSON
  2. Check that Node.js is in your PATH
  3. Try using absolute paths in the configuration

Permission errors

Create the project directory and ensure it's writable:

bash
mkdir -p ~/ascii-projects
chmod 755 ~/ascii-projects

Config file location

If you can't find the config file, check Windsurf's documentation or settings for the exact MCP configuration path for your version.

Next Steps