Installation

Complete installation guide for AsciiKit MCP for Claude Code.

System Requirements

Before installing, make sure you have:

  • Claude Code CLI (latest version)
  • Node.js 18.0.0 or higher
  • npm (comes with Node.js)
  • Internet connection (for license validation)

Checking your Node.js version

node --version

If you see v18.0.0 or higher, you're good to go.

If Node.js isn't installed, download it from nodejs.org

Installation Steps

1. Get your license key

You'll need a license key before installing. Choose one:

Free Trial (recommended for first-time users):

  1. Visit asciikit.com/trial
  2. Enter your email address
  3. Check your email for your license key
  4. You get 10 free uses, no credit card required

Paid Subscription:

  1. Visit asciikit.com and choose a plan
  2. Complete checkout
  3. Receive license key via email

Your license key format:

  • Trial: ak_trial_a1b2c3d4... (32 characters after prefix)
  • Paid: ak_live_a1b2c3d4... (32 characters after prefix)

💡 Save your license key - you'll need it in Step 3.

2. Install the MCP server

Open your terminal and run:

npm install -g asciikit-mcp

This installs the AsciiKit MCP server globally, making it available to Claude Code.

Verify installation

Check that it installed correctly:

asciikit-mcp --version

You should see the current version number (e.g., 5.1.3).

3. Configure Claude Code

The easiest way to configure AsciiKit is with the interactive setup wizard:

asciikit-mcp setup

The wizard will:

  1. ✓ Check your system (Node.js version, config file)
  2. ✓ Prompt for your license key (with format validation)
  3. ✓ Ask if you want global or project-specific installation
  4. ✓ Automatically backup your existing config
  5. ✓ Validate your license key
  6. ✓ Update ~/.claude.json with correct structure

That's it! The wizard handles all the JSON editing, validation, and error handling for you.

Example:

$ asciikit-mcp setup

🎨 AsciiKit Setup Wizard

Checking your system...
✓ Node.js v22.19.0
✓ Found ~/.claude.json
✓ asciikit-mcp v5.2.1 installed

✔ Enter your AsciiKit license key: ak_trial_***
✓ Valid format

✔ How would you like to install AsciiKit?
❯ Global (available in all projects)
  Project-specific (only in current directory)

✓ Backing up ~/.claude.json → ~/.claude.json.backup-2026-02-20
✓ Updated ~/.claude.json
✓ Testing license key... ✓ Valid!

All set! 🎉

Start Claude Code and try:
  claude
  /asciikit-quick Design a login screen

View docs: https://docs.asciikit.com

Note: License validation has a 5-second timeout. If you're on a slow connection and see a timeout error, you can choose to continue anyway - the license will be validated when you first use AsciiKit.

Option B: Manual Configuration (Advanced)

If you prefer to edit ~/.claude.json manually:

Global Configuration (available in all projects):

{
  "mcpServers": {
    "asciikit": {
      "command": "asciikit-mcp",
      "env": {
        "ASCIIKIT_LICENSE_KEY": "your_license_key_here"
      }
    }
  }
}

Project-Specific Configuration (only in one directory):

{
  "projects": {
    "/Users/yourname/path/to/project": {
      "mcpServers": {
        "asciikit": {
          "command": "asciikit-mcp",
          "env": {
            "ASCIIKIT_LICENSE_KEY": "your_license_key_here"
          }
        }
      }
    }
  }
}

⚠️ Important:

  • Replace "your_license_key_here" with your actual license key
  • Ensure valid JSON syntax (no trailing commas, matching brackets)
  • For project-specific, path must match where you run claude (use pwd)

3b. Configure Cursor (Alternative IDE)

If you're using Cursor instead of Claude Code:

  1. Run the setup wizard and select "Cursor" when prompted
  2. The wizard will configure ~/.cursor/mcp.json automatically

Manual configuration for Cursor:

{
  "mcpServers": {
    "asciikit": {
      "command": "asciikit-mcp",
      "env": {
        "ASCIIKIT_LICENSE_KEY": "your_license_key_here"
      }
    }
  }
}

⚠️ Important: Use the global config at ~/.cursor/mcp.json, not project-level .cursor/mcp.json

4. Verify it's working

Start Claude Code in a new terminal session:

claude

Try the AsciiKit commands:

/asciikit-quick
Design a login screen for elderly users

If Claude generates psychologically-informed wireframes, you're all set! 🎉

You can also check that AsciiKit loaded with:

/mcp

You should see asciikit in the MCP servers list.

Platform-Specific Notes

macOS

Using Homebrew?

If you manage Node.js with Homebrew, make sure npm's global bin directory is in your PATH:

echo $PATH | grep npm

You should see something like /usr/local/lib/node_modules/npm/bin

Permission Issues?

If you see EACCES permission errors during installation:

# Option 1: Use npx (recommended)
# Then update your ~/.claude.json to use npx:
{
  "mcpServers": {
    "asciikit": {
      "command": "npx",
      "args": ["-y", "asciikit-mcp@latest"],
      "env": {
        "ASCIIKIT_LICENSE_KEY": "your_key_here"
      }
    }
  }
}

# Option 2: Fix npm permissions (one-time setup)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g asciikit-mcp

Windows

Using PowerShell?

You may need to allow script execution:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Command not found after install?

Check if npm's global directory is in your PATH:

npm config get prefix

Add that directory to your system PATH if it's not already there.

Config file location on Windows:

C:\Users\YourUsername\.claude.json

Linux

Permission denied?

Use sudo for global installation:

sudo npm install -g asciikit-mcp

Or fix npm permissions to avoid sudo:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g asciikit-mcp

Updating AsciiKit

To update to the latest version:

npm update -g asciikit-mcp

To check for updates without installing:

npm outdated -g asciikit-mcp

Uninstalling

If you need to uninstall:

npm uninstall -g asciikit-mcp

Then remove the "asciikit" section from your ~/.claude.json file.

Troubleshooting

"asciikit-mcp: command not found"

Cause: The global npm bin directory isn't in your PATH.

Fix:

  1. Find where npm installs global packages:
    npm config get prefix
  2. Add that directory's bin folder to your PATH
  3. On macOS/Linux, edit ~/.zshrc or ~/.bashrc:
    export PATH="/path/to/npm/bin:$PATH"
  4. Restart your terminal

"Invalid license key"

Cause: License key is wrong or improperly formatted in config.

Fix:

  1. Double-check your license key in the email
  2. Make sure it's wrapped in quotes in ~/.claude.json
  3. Verify it starts with ak_trial_ or ak_live_
  4. Copy-paste directly (don't retype)
  5. Check for extra spaces or line breaks

AsciiKit commands not available

Cause: MCP server not loaded or wrong directory for project-specific config.

Fix:

  1. Check if AsciiKit is in the MCP list:
    claude
/mcp
  2. If using project-specific config, verify the path in ~/.claude.json matches your current directory (pwd)
  3. If using global config, make sure it's under the root "mcpServers" not inside "projects"
  4. Validate JSON at jsonlint.com
  5. Start a fresh claude session

"License validation failed: Network error"

Cause: Can't reach the license API server.

Fix:

  1. Check your internet connection
  2. Verify the license API is accessible:
    curl https://asciikit-license-api.currently-studio.workers.dev/health
  3. Check if your firewall is blocking connections
  4. Try again in a few minutes (temporary server issue)

Trial uses exhausted

Cause: You've used all 10 free trial uses.

What to do:

  • Subscribe at asciikit.com for unlimited use
  • Or contact support at hello@asciikit.com if you have issues

Need more help?

Next steps

Now that AsciiKit is installed: