Installation

This guide covers the complete installation process and configuration for different MCP clients and package managers.

Prerequisites

Before installing AccessibilityHub, ensure you have:

Node.js ≥ 20

Check your version:

node --version

Download from nodejs.org

Chrome/Chromium

Automatically downloaded by Puppeteer on first run.No manual installation needed.

Package Installation

Choose your preferred installation method:

npx (Recommended)
npm
pnpm
Local Development

Run AccessibilityHub without installing:

npx -y accessibility-hub

This is the recommended approach for MCP client configurations. It ensures you always use the latest version and requires no global installation.

The -y flag automatically accepts the prompt to download and run the package.

Install globally with npm:

npm install -g accessibility-hub

Verify installation:

accessibility-hub --version

On macOS/Linux, you may need sudo for global installs, or configure npm to use a user-writable directory.

Install globally with pnpm:

pnpm add -g accessibility-hub

Verify installation:

accessibility-hub --version

For contributing or testing local changes:

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

See Contributing Guide for details.

MCP Client Configuration

Configure your preferred MCP client to use AccessibilityHub. All configurations use npx to ensure you always have the latest version.

Claude Desktop

Add AccessibilityHub to your Claude Desktop configuration file:

Locate configuration file

Find your configuration file based on your platform:

Platform	Configuration Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

Edit configuration

Add the following to your config file:

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

If you already have other MCP servers, add accessibility-hub to the existing mcpServers object.

Restart Claude Desktop

Completely quit and restart Claude Desktop for changes to take effect.

Optional: Environment Variables

Configure logging level:

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

Cursor

One-Click Install
Manual Install

Click the button below to automatically install:

After clicking, restart Cursor.

Add to .cursor/mcp.json in your project or global config:

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

Project-level config: .cursor/mcp.json in your project rootGlobal config: Location varies by platform (check Cursor settings)Restart Cursor after editing.

Windsurf

Locate config file

Windsurf uses: ~/.codeium/windsurf/mcp_config.json

Add configuration

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

Restart Windsurf

Completely restart Windsurf for changes to take effect.

Claude Code (CLI)

Add the server using the Claude CLI:

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

Verify it was added:

claude mcp list

You should see accessibility-hub in the list of servers.

Local Development Configuration

For testing local changes or contributing to AccessibilityHub:

Clone and build

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

Point to local build

Update your MCP client config to use the local build:

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

Replace /absolute/path/to/A-I-ccesibility with your actual path.

Restart client

Restart your MCP client to load the local build.

Remember to run pnpm build after making changes to the source code.

Environment Variables

Configure server behavior with environment variables:

Variable	Description	Default	Options
`LOG_LEVEL`	Logging verbosity	`info`	`debug`, `info`, `warn`, `error`

Example with Debug Logging

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

Verify Installation

After configuring your MCP client:

Restart your MCP client

Completely quit and restart your MCP client (Claude Desktop, Cursor, Windsurf, etc.). A simple reload is not sufficient.

Check available tools

Ask the AI assistant:

What accessibility tools are available?

You should see:

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

Test with a simple analysis

Analyze the accessibility of https://example.com

The assistant should use one or more tools to analyze the page and return results.

On first run, Puppeteer will automatically download Chrome/Chromium. This may take a few minutes and requires an internet connection.

Troubleshooting

Server not starting

Check Node.js version:

node --version

Must be ≥ 20.0.0Verify npx can find the package:

npx -y accessibility-hub --version

Check JSON syntax: Use a JSON validator to verify your config file has valid syntax.Review client logs:

Claude Desktop: Check ~/Library/Logs/Claude/ (macOS) or equivalent
Cursor: Check the output panel
CLI: Errors are shown directly

Chrome/Puppeteer issues

First run download: Puppeteer automatically downloads Chrome on first run. This may take 2-5 minutes.Linux dependencies: On Linux servers, install required libraries:

apt-get install libnss3 libatk1.0-0 libatk-bridge2.0-0 \
  libcups2 libxcomposite1 libxrandr2 libgbm1 \
  libasound2 libpangocairo-1.0-0 libxss1

Behind a proxy: If behind a proxy, set environment variable and install Chrome manually:

export PUPPETEER_SKIP_DOWNLOAD=true

Headless mode issues: Chrome runs in headless mode by default. If you encounter issues, check that your system supports headless Chrome.

Permission errors

Global npm install on macOS/Linux:

sudo npm install -g accessibility-hub

Alternative - configure npm for user directory:

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

Use npx instead: The npx approach requires no global installation and avoids permission issues entirely.

Tools not appearing in client

Restart completely: Make sure you completely quit and restart your MCP client, not just reload.Check server status: Look for AccessibilityHub in your client’s MCP servers list.Try explicit tool call: Ask: “Use the analyze-with-axe tool to analyze https://example.com”Check connection logs: Look for connection errors in your client’s logs or output panel.

Version conflicts

Using npx: npx always fetches the latest version. No action needed.Global install: Update to the latest version:

npm update -g accessibility-hub
# or
pnpm update -g accessibility-hub

Check current version:

accessibility-hub --version

Platform-Specific Notes

macOS
Windows
Linux
WSL (Windows Subsystem for Linux)

No special requirements - works out of the box after Node.js installation.Global npm installs may require sudo or npm configuration for user directory.Recommended: Use npx to avoid permission issues.

Use Command Prompt or PowerShell for npm commands.Path issues: Ensure npm global bin directory is in PATH:

npm config get prefix

Add <prefix> to your PATH environment variable.Alternative: Use npx which requires no PATH configuration.

Install Chrome dependencies (required for Puppeteer):

# Debian/Ubuntu
sudo apt-get update
sudo apt-get install -y libnss3 libatk1.0-0 \
  libatk-bridge2.0-0 libcups2 libxcomposite1 \
  libxrandr2 libgbm1 libasound2 libpangocairo-1.0-0 libxss1

# RHEL/CentOS/Fedora
sudo yum install -y nss atk at-spi2-atk cups-libs \
  libXcomposite libXrandr libgbm alsa-lib pango libXScrnSaver

Headless servers: Chrome requires a display. Use Xvfb if needed:

sudo apt-get install xvfb
xvfb-run npx -y accessibility-hub

Follow Linux instructions for Chrome dependencies.Display issues: You may need to configure X11 forwarding or use Xvfb:

sudo apt-get install xvfb

Performance: Native Windows installation typically performs better than WSL.

Next Steps

Quick Start

Get started with your first analysis

MCP Client Setup

Detailed setup for each MCP client

Workflows

Recommended workflows for common tasks

Troubleshooting

Understanding and acting on results

Get Started

Core Concepts

Guides

Contributing

Prerequisites

Node.js ≥ 20

Chrome/Chromium

Package Installation

MCP Client Configuration

Claude Desktop

Optional: Environment Variables

Cursor

Windsurf

Claude Code (CLI)

Local Development Configuration

Environment Variables

Example with Debug Logging

Verify Installation

Troubleshooting

Platform-Specific Notes

Next Steps

Quick Start

MCP Client Setup

Workflows

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Contributing

​Prerequisites

Node.js ≥ 20

Chrome/Chromium

​Package Installation

​MCP Client Configuration

​Claude Desktop

​Optional: Environment Variables

​Cursor

​Windsurf

​Claude Code (CLI)

​Local Development Configuration

​Environment Variables

​Example with Debug Logging

​Verify Installation

​Troubleshooting

​Platform-Specific Notes

​Next Steps

Quick Start

MCP Client Setup

Workflows

Troubleshooting

Build docs developers (and LLMs) love

Prerequisites

Package Installation

MCP Client Configuration

Claude Desktop

Optional: Environment Variables

Cursor

Windsurf

Claude Code (CLI)

Local Development Configuration

Environment Variables

Example with Debug Logging

Verify Installation

Troubleshooting

Platform-Specific Notes

Next Steps