ASCII Motion MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to create, animate, and export ASCII art from the ASCII Motion app, using natural language.

What is this?

ASCII Motion MCP allows you to use AI assistants like Claude, GitHub Copilot, and Cursor to:

🎨 Draw ASCII art - Create pixel art and text graphics with characters
🎬 Animate - Build frame-by-frame animations with onion skinning
📥 Import - Convert images to ASCII art with full control
📤 Export - Save as PNG, GIF, MP4, HTML, React, or CLI components
🌈 Apply effects - Add digital rain, noise, color shifts, and more

All through natural language prompts!

Quick Start

Prerequisites

Node.js 18+
An MCP-compatible AI client (Claude Desktop, VS Code + Copilot, Cursor, etc.)

Installation

npm install -g ascii-motion-mcp

Verify installation:

ascii-motion-mcp --help

Client Setup

Important: The --live flag is required for all setups. Without it, the MCP tools have no visual output. After configuring your client, you must also connect the browser to see your AI's work.

Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ascii-motion": {
      "command": "ascii-motion-mcp",
      "args": ["--live", "--project-dir", "/path/to/your/projects"]
    }
  }
}

Restart Claude Desktop after saving.

VS Code with GitHub Copilot

Install the GitHub Copilot extension
Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "ascii-motion": {
      "command": "npx",
      "args": [
        "ascii-motion-mcp",
        "--live",
        "--project-dir",
        "${workspaceFolder}"
      ],
      "type": "stdio"
    }
  }
}

Or if you've installed globally (npm install -g ascii-motion-mcp):

{
  "servers": {
    "ascii-motion": {
      "command": "ascii-motion-mcp",
      "args": [
        "--live",
        "--project-dir",
        "${workspaceFolder}"
      ],
      "type": "stdio"
    }
  }
}

Restart VS Code completely (not just reload window)
Open Copilot Chat - the MCP tools should now be available!

Note: VS Code spawns the MCP server automatically when Copilot needs it. You don't run the server manually.

Connect the Browser (Optional)

To see edits in real-time:

Ask Copilot: "What is the MCP auth token?"
Open ascii-motion.app
Click ☰ → MCP Connection
Paste the token and click Connect

GitHub Copilot CLI

Install GitHub CLI and Copilot extension:

# Install GitHub CLI
brew install gh  # macOS
# or: winget install GitHub.cli  # Windows

# Install Copilot extension
gh extension install github/gh-copilot

# Login
gh auth login

Create/edit ~/.config/gh-copilot/config.yml:

mcpServers:
  ascii-motion:
    command: ascii-motion-mcp
    args:
      - --live
      - --project-dir
      - ~/ascii-art-projects

Use in terminal:

gh copilot chat "Create an 8-frame animation of a bouncing ball"

Cursor

Open Cursor Settings (Cmd+, / Ctrl+,)
Search for "MCP" in settings
Click "Edit in settings.json" and add:

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

Restart Cursor

Windsurf

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "ascii-motion": {
      "command": "ascii-motion-mcp", 
      "args": ["--live", "--project-dir", "/path/to/projects"]
    }
  }
}

Connect the Browser

After configuring your AI client, you must connect the ASCII Motion browser app to see visual output:

Get the auth token - Ask your AI: "What is the MCP auth token?"
Open ASCII Motion - Go to ascii-motion.app
Open MCP Connection - Click the hamburger menu (☰) → MCP Connection
Paste the token - Enter the auth token and click Connect

You should see a green "Connected" status. Now your AI's edits appear in real-time!

CLI Options

ascii-motion-mcp [options]

Options:
  -d, --project-dir PATH  Project directory for file operations (default: cwd)
  -l, --live              Enable live browser sync via WebSocket (REQUIRED)
  -p, --port PORT         WebSocket port for live mode (default: 9876)
  -h, --help              Show help
  -v, --version           Show version

Example Prompts

Once configured, try these prompts with your AI assistant:

Create Art:

"Create a 40x20 canvas with a pixel art heart in red"

Import & Convert:

"Import the image at ./photo.jpg and convert it to ASCII using block characters"

Animate:

"Create an 8-frame animation of a walking stick figure"

Apply Effects:

"Add a digital rain effect with green characters"

Export:

"Export this animation as a GIF with 2x size"

CLI Components:

"Export as an Ink component for my Node.js CLI app"

Available Tools (69 total)

Canvas Tools

set_cell, get_cell, clear_cell, set_cells_batch, paste_ascii_block, fill_region, resize_canvas, clear_canvas

Frame Tools

add_frame, delete_frame, duplicate_frame, go_to_frame, list_frames, set_frame_duration, set_frame_name

Animation Tools

copy_frame_and_modify, shift_frame_content, flip_region, copy_region_to_frame, interpolate_frames

Project Tools

new_project, save_project, load_project, get_project_info, list_project_files, set_project_name

Preview Tools

get_canvas_summary, get_canvas_preview, get_canvas_ascii, get_frame_diff, describe_animation

Selection Tools

select_rectangle, select_by_color, get_selection, clear_selection, apply_to_selection, delete_selection_content

Palette Tools

list_character_palettes, get_character_palette, list_color_palettes, get_color_palette, get_active_colors, set_foreground_color, set_background_color, set_selected_character, suggest_palette_for_style

Import Tools

import_image, import_video, import_ascii_text

Effects Tools

apply_effect, get_color_stats, batch_recolor, batch_replace_char

Generator Tools

run_generator, preview_generator

Export Tools

export_text, export_json, export_session, export_html, export_react, export_ansi, export_ink, export_bubbletea, export_opentui, export_image, export_video

History Tools

undo, redo, get_history_status

MCP Resources

The server exposes these resources for state introspection:

project://state - Full project state snapshot
project://canvas - Current frame canvas data
project://frames - Frame list with metadata
project://selection - Current selection state
project://history - Undo/redo history
project://ascii - Plain text ASCII preview

Requirements

Node.js 18+ - Required
sharp (optional) - For image import: npm install sharp
ffmpeg (optional) - For video export: brew install ffmpeg

Troubleshooting

"Command not found"

Make sure npm global bin is in your PATH:

npm bin -g
# Add the output to your PATH if needed

Tools not appearing

Restart your AI client after configuration changes. Check that the config file is valid JSON.

Live mode not connecting

Ensure port 9876 is available
Check that you're connecting from localhost
Verify the auth token is correct

No visual output

Make sure you're using the --live flag AND have connected the browser via MCP Connection.

Links

License

MIT License - see LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 65 Commits
docs		docs
src		src
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
README.md		README.md
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
run-server-live.sh		run-server-live.sh
run-server.sh		run-server.sh
test-mcp-call.mjs		test-mcp-call.mjs
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation