/ docs
Open App

VS Code + GitHub Copilot Setup

Use the ASCII Motion MCP server with GitHub Copilot in VS Code for AI-powered ASCII art creation directly in your editor.

Prerequisites

Installation

Step 1: Create the MCP Configuration

Create .vscode/mcp.json in your workspace:

  1. Open your project folder in VS Code
  2. Create a .vscode folder if it doesn't exist
  3. Create a file named mcp.json inside .vscode
  4. Add the following configuration:

Using npx (no install required):

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

Or with global install:

First install: npm install -g ascii-motion-mcp

json
{
  "servers": {
    "ascii-motion": {
      "command": "ascii-motion-mcp",
      "args": [
        "--live",
        "--project-dir",
        "${workspaceFolder}"
      ],
      "type": "stdio"
    }
  }
}
How It Works
  • The --live flag enables real-time sync with the browser editor
  • ${workspaceFolder} uses your current workspace as the project directory

Step 2: Restart VS Code and Start Server

Important: You must fully quit and reopen VS Code (not just reload the window) for MCP configuration changes to take effect.

Option 1: Start server in the VScode GUI:

  1. Start the server from the mcp.json file by pressing the start button under "servers".
  2. Click on the more button and navigate to show output.
  3. Check the output for the auth token. Copy that auth token to your clipboard.

Option 2: Start server in the terminal:

  1. Run npx ascii-motion-mcp --live in the terminal.
  2. Copy the auth token from the terminal output onto your clipboard.

Step 3: Connect in the Browser

  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 and click Connect

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

Example Prompts for VS Code

Create Documentation Art

"Create an ASCII art banner that says 'API Reference' for my README"

Generate Loading Spinner

"Create an 8-frame loading spinner animation and export it as a TypeScript constant"

Convert Image

"Import ./assets/logo.png and convert it to ASCII art, then save as ASCII in my docs folder"

Create CLI Component

"Create a bouncing ball animation and export it as an Ink component for my CLI app"

Troubleshooting

Tools not appearing in Copilot

  1. Verify your .vscode/mcp.json is valid JSON
  2. Check VS Code's Output panel (View → Output) and select "GitHub Copilot"
  3. Look for MCP-related messages
  4. Try using an absolute path: "/usr/local/bin/ascii-motion-mcp"

"Cannot find module" errors

Ensure the command path is correct in .vscode/mcp.json:

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

Permission errors

Make sure the project directory exists and is writable:

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

Next Steps