MCP Client Setup

This guide provides comprehensive setup instructions for all supported MCP clients, including troubleshooting tips and advanced configuration options.

Quick start? See the Installation Guide for basic setup. This guide covers detailed configuration and troubleshooting.

Prerequisites

Before setting up any MCP client:

Verify Node.js version

node --version

Required: Node.js ≥ 20If you need to update: Download Node.js

Test npx access

npx --version

Should return npm version (npx is bundled with npm)

Verify accessibility-hub package

npx -y accessibility-hub --version

This downloads and tests the package

Chrome/Chromium is required for browser-based analysis. Puppeteer will download it automatically on first run (~170MB).

Claude Desktop

Configuration

Locate config file

Find your configuration file:

macOS
Windows
Linux

~/Library/Application Support/Claude/claude_desktop_config.json

Open with:

open -a TextEdit ~/Library/Application\ Support/Claude/claude_desktop_config.json

%APPDATA%\Claude\claude_desktop_config.json

Open with:

notepad %APPDATA%\Claude\claude_desktop_config.json

~/.config/Claude/claude_desktop_config.json

Open with:

nano ~/.config/Claude/claude_desktop_config.json

Add configuration

If file is empty or doesn’t exist:

{
  "mcpServers": {
    "accessibility-hub": {
      "command": "npx",
      "args": ["-y", "accessibility-hub"]
    }
  }
}

If you already have other servers:

{
  "mcpServers": {
    "other-server": {
      "command": "node",
      "args": ["/path/to/other-server.js"]
    },
    "accessibility-hub": {
      "command": "npx",
      "args": ["-y", "accessibility-hub"]
    }
  }
}

Restart Claude Desktop

Important: Completely quit and restart Claude Desktop

macOS: Cmd+Q, then reopen
Windows: Right-click system tray icon → Quit, then reopen
Linux: Close all windows, then reopen

Use “Quit” not just closing the window. The app must fully restart.

Verify setup

In Claude Desktop, type:

What tools do you have available?

You should see:

analyze-with-axe
analyze-with-pa11y
analyze-with-lighthouse
analyze-contrast
analyze-mixed

Optional: Environment Variables

Configure logging and behavior:

{
  "mcpServers": {
    "accessibility-hub": {
      "command": "npx",
      "args": ["-y", "accessibility-hub"],
      "env": {
        "LOG_LEVEL": "debug",
        "PUPPETEER_EXECUTABLE_PATH": "/path/to/chrome"
      }
    }
  }
}

Available environment variables:

Variable	Values	Description
`LOG_LEVEL`	`error`, `warn`, `info`, `debug`	Logging verbosity
`PUPPETEER_EXECUTABLE_PATH`	Path to Chrome	Use specific Chrome binary
`PUPPETEER_SKIP_DOWNLOAD`	`true`	Skip Chromium download (use system Chrome)

Troubleshooting

Server not appearing in Claude

Symptoms: No accessibility tools availableSolutions:

Verify JSON syntax (use JSONLint)
Check file location is correct for your OS
Ensure you fully quit and restarted Claude (not just closed window)
Check Claude logs:
- macOS: ~/Library/Logs/Claude/
- Windows: %APPDATA%\Claude\logs\
- Linux: ~/.config/Claude/logs/

Server fails to start

Symptoms: Error message about server startupSolutions:

Verify Node.js version: node --version (≥ 20)
Test npx directly: npx -y accessibility-hub --version
Check permissions on config file

Try absolute path instead of npx:

{
  "command": "node",
  "args": ["/absolute/path/to/node_modules/.bin/accessibility-hub"]
}

Puppeteer/Chrome issues

Symptoms: Errors about Chrome or PuppeteerSolutions:

Let Puppeteer download Chrome automatically (first run takes time)

Or install Chrome system-wide and use:

{
  "env": {
    "PUPPETEER_SKIP_DOWNLOAD": "true",
    "PUPPETEER_EXECUTABLE_PATH": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
  }
}

Common Chrome paths:
- macOS: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
- Windows: C:\Program Files\Google\Chrome\Application\chrome.exe
- Linux: /usr/bin/google-chrome

Permission errors

Symptoms: EACCES or permission denied errorsSolutions:

Run without sudo (npm global installs should not require sudo)

Configure npm to use user directory:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile

Use npx (recommended) which doesn’t require global install

Cursor

One-Click Install (Recommended)

Click to automatically install:

After clicking, restart Cursor.

Manual Install

Decide: Project or Global

Project-level (recommended for team collaboration):

Config file: .cursor/mcp.json in your project root
Only active in this project
Can be committed to git

Global (personal use across all projects):

Config file location varies by OS
Active in all Cursor windows
Check Cursor settings for location

Create/edit config file

Project-level:

mkdir -p .cursor
touch .cursor/mcp.json

Add configuration:

{
  "mcpServers": {
    "accessibility-hub": {
      "command": "npx",
      "args": ["-y", "accessibility-hub"]
    }
  }
}

Restart Cursor

Completely restart Cursor (Cmd+Q / Alt+F4, then reopen)

Verify setup

Open Cursor’s command palette and ask:

What MCP tools are available?

Troubleshooting

Which config file is being used?

Cursor checks configs in this order:

Project-level: .cursor/mcp.json
Global config (OS-specific)

To check which is active:

Open Cursor settings
Search for “MCP”
View active configuration path

Project config not working

Solutions:

Ensure .cursor/mcp.json is in project root (not nested)
Check JSON syntax
Restart Cursor from project root directory
Try global config as alternative

Team collaboration setup

For team projects, commit .cursor/mcp.json:

# .gitignore
# Don't ignore .cursor/mcp.json so team can use it
!.cursor/mcp.json

Team members need:

Node.js ≥ 20 installed
Pull the repo with .cursor/mcp.json
Restart Cursor

No manual configuration needed!

Windsurf

Configuration

Locate config file

Windsurf config location:

~/.codeium/windsurf/mcp_config.json

Create directory if it doesn’t exist:

mkdir -p ~/.codeium/windsurf
touch ~/.codeium/windsurf/mcp_config.json

Add configuration

{
  "mcpServers": {
    "accessibility-hub": {
      "command": "npx",
      "args": ["-y", "accessibility-hub"]
    }
  }
}

Restart Windsurf

Completely quit and restart Windsurf

Verify setup

In Windsurf, ask:

List available MCP tools

Troubleshooting

Config file not found

Solutions:

Create directory structure:
```
mkdir -p ~/.codeium/windsurf
```
Verify path (may vary by Windsurf version)
Check Windsurf documentation for config location

Windsurf-specific issues

Windsurf is built on VSCode but uses Codeium config locations.If issues persist:

Check Windsurf version (may need update)
Verify MCP support is enabled in settings
Check Windsurf logs for errors

Claude Code CLI

Installation

Install Claude CLI if not already installed:

# Install Claude CLI
npm install -g @anthropic-ai/claude-cli

# Verify installation
claude --version

Configuration

Add MCP server

claude mcp add accessibility-hub -- npx -y accessibility-hub

The -- separates Claude CLI args from the server command

Verify setup

List configured servers:

claude mcp list

You should see:

accessibility-hub: npx -y accessibility-hub

Test usage

claude "Analyze the accessibility of https://example.com"

Advanced Usage

Pipe content to Claude

Analyze HTML from stdin:

curl https://example.com | claude "Check this HTML for accessibility issues"

Use in scripts

#!/bin/bash

# Analyze multiple URLs
urls=(
  "https://example.com/page1"
  "https://example.com/page2"
  "https://example.com/page3"
)

for url in "${urls[@]}"; do
  echo "Analyzing $url..."
  claude "Analyze $url and show only critical issues" > "report-$(basename $url).txt"
done

Troubleshooting

Command not found: claude

Solutions:

Install Claude CLI:

npm install -g @anthropic-ai/claude-cli

Verify npm global bin is in PATH:
```
echo $PATH | grep npm
```

Use full path:

$(npm bin -g)/claude mcp add accessibility-hub -- npx -y accessibility-hub

Server not starting

Solutions:

Test server directly:
```
npx -y accessibility-hub --version
```

Remove and re-add:

claude mcp remove accessibility-hub
claude mcp add accessibility-hub -- npx -y accessibility-hub

Check Claude CLI logs:
```
claude mcp logs accessibility-hub
```

Authentication issues

Ensure Claude CLI is authenticated:

claude auth login

Follow prompts to authenticate with your Anthropic account

Local Development Setup

For contributing or testing local changes:

Clone and build

git clone https://github.com/drzkn/A-I-ccesibility.git
cd A-I-ccesibility
pnpm install
pnpm build

Point MCP client to local build

Update your MCP client config:

{
  "mcpServers": {
    "accessibility-hub": {
      "command": "node",
      "args": ["/absolute/path/to/A-I-ccesibility/dist/server.js"]
    }
  }
}

Use absolute path, not relative path or ~

Development with watch mode

In the project directory:

pnpm dev

This rebuilds on file changes. Restart your MCP client to pick up changes.

Debug with MCP Inspector

pnpm inspect

Opens MCP Inspector for interactive debugging

Proxy and Firewall Configuration

HTTP Proxy

If behind a corporate proxy:

{
  "mcpServers": {
    "accessibility-hub": {
      "command": "npx",
      "args": ["-y", "accessibility-hub"],
      "env": {
        "HTTP_PROXY": "http://proxy.company.com:8080",
        "HTTPS_PROXY": "http://proxy.company.com:8080",
        "NO_PROXY": "localhost,127.0.0.1"
      }
    }
  }
}

Self-Signed Certificates

For internal sites with self-signed certs:

{
  "options": {
    "browser": {
      "ignoreHTTPSErrors": true
    }
  }
}

Only use ignoreHTTPSErrors: true for internal testing, never for public sites.

Verifying Installation

Test Commands

After setup, verify with these test prompts:

List Tools
List Prompts
Test Analysis
Test Contrast

What accessibility testing tools do you have?

Expected: List of 5 tools (analyze-with-axe, analyze-with-pa11y, etc.)

What accessibility prompts are available?

Expected: List of 8 prompts (full-accessibility-audit, etc.)

Analyze the accessibility of https://example.com

Expected: Analysis results with issues found

Check the color contrast of https://example.com

Expected: Contrast analysis with ratios

Common Issues Checklist

If tools aren’t working:

Node.js version ≥ 20
Config file JSON is valid
Config file is in correct location
MCP client fully restarted (quit and reopened)
npx works: npx -y accessibility-hub --version
Firewall allows outbound HTTPS
Chrome/Chromium download completed (first run)

Multi-Client Setup

Using multiple MCP clients? You can configure all of them:

# Claude Desktop
code ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Cursor (project)
mkdir -p .cursor && code .cursor/mcp.json

# Windsurf
code ~/.codeium/windsurf/mcp_config.json

# Claude CLI
claude mcp add accessibility-hub -- npx -y accessibility-hub

All use the same configuration format, so you can copy/paste.

Next Steps

Quickstart

Try your first accessibility analysis

Workflows

Learn common testing workflows

Effective Prompts

Write better accessibility prompts

Troubleshooting

Advanced debugging techniques

Get Started

Core Concepts

Guides

Contributing

Prerequisites

Claude Desktop

Configuration

Optional: Environment Variables

Troubleshooting

Cursor

One-Click Install (Recommended)

Manual Install

Troubleshooting

Windsurf

Configuration

Troubleshooting

Claude Code CLI

Installation

Configuration

Advanced Usage

Troubleshooting

Local Development Setup

Proxy and Firewall Configuration

HTTP Proxy

Self-Signed Certificates

Verifying Installation

Test Commands

Common Issues Checklist

Multi-Client Setup

Next Steps

Quickstart

Workflows

Effective Prompts

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Contributing

​Prerequisites

​Claude Desktop

​Configuration

​Optional: Environment Variables

​Troubleshooting

​Cursor

​One-Click Install (Recommended)

​Manual Install

​Troubleshooting

​Windsurf

​Configuration

​Troubleshooting

​Claude Code CLI

​Installation

​Configuration

​Advanced Usage

​Troubleshooting

​Local Development Setup

​Proxy and Firewall Configuration

​HTTP Proxy

​Self-Signed Certificates

​Verifying Installation

​Test Commands

​Common Issues Checklist

​Multi-Client Setup

​Next Steps

Quickstart

Workflows

Effective Prompts

Troubleshooting

Build docs developers (and LLMs) love

Prerequisites

Claude Desktop

Configuration

Optional: Environment Variables

Troubleshooting

Cursor

One-Click Install (Recommended)

Manual Install

Troubleshooting

Windsurf

Configuration

Troubleshooting

Claude Code CLI

Installation

Configuration

Advanced Usage

Troubleshooting

Local Development Setup

Proxy and Firewall Configuration

HTTP Proxy

Self-Signed Certificates

Verifying Installation

Test Commands

Common Issues Checklist

Multi-Client Setup

Next Steps