Squidler MCP Server

Model Context Protocol (MCP) server that exposes Squidler accessibility and quality issues to AI coding agents like Claude Code.

What is MCP?

Model Context Protocol (MCP) is a standard protocol that allows AI coding agents to access external data sources and tools. This MCP server connects Claude Code (and other MCP-compatible tools) to your Squidler accessibility reports, enabling automated problem fixing.

Features

• Fetch Problems: Get detailed accessibility and quality issues for any site
• Rich Context: Includes HTML snippets, CSS selectors, fix instructions, and screenshots
• Problem Management: Mark problems as resolved or dismissed
• Test Case Management: Create and manage automated test cases for your site
• Credentials Access: Retrieve site credentials for authenticated test scenarios

Installation

The easiest way to use the Squidler MCP server is via the published npm package:

npm install -g @squidlerio/mcp-problems

Then configure your MCP client (see Configuration section below).

Prerequisites:

• Node.js 18 or higher
• API Key from your Squidler site (see "Getting an API Key" below)

Getting an API Key

To use the MCP server, you need an API key from your Squidler site:

1. Log in to your Squidler account at https://squidler.io
2. Navigate to your site
3. Go to Settings → Developer
4. Click Add to create a new API key
5. Give it a descriptive name (e.g., "Claude Code MCP")
6. Copy the API key - you'll need it for configuration

Important: The API key is shown only once. Store it securely.

Configuration

{
  "mcpServers": {
    "squidler": {
      "command": "npx",
      "args": ["-y", "@squidlerio/mcp-problems"],
      "env": {
        "SQUIDLER_API_URL": "https://api.squidler.io",
        "SQUIDLER_API_KEY": "your-site-api-key-here"
      }
    }
  }
}

Important: Replace your-site-api-key-here with the API key you created in the "Getting an API Key" section.

Environment Variables

• SQUIDLER_API_URL: Base URL of the Squidler API (use https://api.squidler.io)
• SQUIDLER_API_KEY: Required. Your site API key for authentication (get from Settings → Developer)

Usage

Once configured, the MCP server provides tools to your AI coding agent for fetching and managing accessibility problems.

Typical Workflow

1. Your AI agent fetches problems (typically one at a time to avoid context overflow)
2. The agent analyzes the issue and makes code changes
3. The agent marks the problem as resolved or dismissed (if false positive)
4. Process repeats until all actionable problems are addressed

Example Interactions

Example 1: Fix all problems

User: "Please fix all issues in my website using the Squidler MCP server"

Agent: [Calls get_site_problems]
Agent: "I found 47 total issues. Let me start with the first one..."

Agent: [Analyzes first problem, makes code changes]
Agent: "Fixed missing alt text on SVG element. Marking as resolved..."
Agent: [Calls resolve_problem with problemNumber="42"]

Agent: [Calls get_site_problems again]
Agent: "46 issues remaining. Working on the next one..."
Agent: [Continues until totalProblems reaches 0]

Example 2: Fix only accessibility problems

User: "Please fix only accessibility issues in my website using the Squidler MCP server"

Agent: [Calls get_site_problems with suiteType="Accessibility"]
Agent: "I found 23 accessibility issues. Let me start with the first one..."

Agent: [Analyzes and fixes accessibility problems]
Agent: [Continues until all accessibility problems are resolved]

Example 3: Fix only broken links and images

User: "Please fix all broken links and images using the Squidler MCP server"

Agent: [Calls get_site_problems with suiteType="Functionality"]
Agent: "I found 15 functionality issues. Let me start with the first one..."

Agent: [Analyzes and fixes functionality problems like broken links, images, etc.]
Agent: [Continues until all functionality problems are resolved]

Example 4: Create a test case

User: "Create a test case that verifies users can log in and access their profile"

Agent: [Calls get_test_cases to check for duplicates]
Agent: "I don't see a similar test case. Does this test require authentication?"
User: "Yes, it requires login"

Agent: [Calls get_credentials]
Agent: "I found these credentials: [email protected]. Would you like to use this for the test?"
User: "Yes"

Agent: [Calls create_test_case with complete workflow including login steps]
Agent: "Created test case 'Login and Access Profile' with 7 steps including login, navigation, and verification. You can run it in the Squidler UI."

Available Tools

Note: The site is automatically determined from your API key. You don't need to specify a site ID - the API key is site-specific.

get_site_problems

Fetch accessibility/quality problems with pagination. Returns actionable problems (NEW, IN_PROGRESS, RECURRING, REGRESSION) with total count.

Parameters:

• limit (optional): Number of problems to return (default: 1, max: 100)
  • Recommended: Keep at 1 to avoid context overflow
• offset (optional): Skip this many problems (default: 0)
  • Recommended: Usually stay at 0 and resolve problems instead
• suiteType (optional): Filter by problem suite type - valid values: "Accessibility", "Functionality", "Language"
  • Accessibility: WCAG compliance issues (e.g., missing alt text, color contrast, ARIA attributes)
  • Functionality: Technical issues (e.g., broken links, broken images, console errors, dead ends)
  • Language: Content quality issues (e.g., spelling, grammar, style)

Response:

{
  "siteId": "site_abc123",
  "siteUrl": "https://example.com",
  "totalProblems": 47,
  "returnedProblems": 1,
  "offset": 0,
  "problems": [
    {
      "problemNumber": "42",
      "ruleId": "svg-img-alt",
      "description": "SVG elements with img role must have alternative text",
      "htmlSnippet": "<svg role=\"img\">...</svg>",
      "cssSelectors": ["body > svg"],
      "fixInstructions": "Add a <title> element or aria-label",
      "helpUrl": "https://dequeuniversity.com/rules/axe/...",
      "screenshotUrl": "https://squidler.io/api/checks/check-123/runs/0/assets/screenshot.webp",
      "pageUrl": "https://example.com/home",
      "pageTitle": "Home Page",
      "problemType": "AxeProblem",
      "tags": ["wcag2a", "cat.text-alternatives"]
    }
  ]
}

Important: After fixing a problem, you MUST call resolve_problem with the problem number to remove it from the actionable list.

resolve_problem

Mark a problem as resolved after fixing it in your codebase. This removes it from the actionable problems list.

Parameters:

• problemNumber (required): The problem number to mark as resolved (e.g., "42")

Example:

{
  "problemNumber": "42"
}

dismiss_problem

Mark a problem as dismissed. Use this when a reported issue is not actually a problem (false positive).

Parameters:

• problemNumber (required): The problem number to mark as dismissed (e.g., "42")

Example:

{
  "problemNumber": "42"
}

get_credentials

Fetch all credentials (login accounts) configured for the site. Returns credential IDs and usernames (passwords are NOT exposed).

When to use: Use this when creating test cases that require authentication to see what credentials are available.

Parameters: None

Example response:

{
  "credentials": [
    {
      "id": "cred_abc123",
      "username": "[email protected]"
    }
  ],
  "totalCount": 1
}

get_test_cases

Fetch all test cases for the site. Use this to see what test cases already exist before creating new ones to avoid duplicates.

Parameters: None

Example response:

{
  "testCases": [
    {
      "id": "tc_xyz789",
      "siteId": "site_abc123",
      "name": "Login and Access Dashboard",
      "refinedTestCases": [
        "Navigate to login page",
        "Enter credentials",
        "Submit form",
        "Verify dashboard loads"
      ],
      "goals": [
        {
          "id": "goal_123",
          "goalText": "User successfully authenticates"
        }
      ],
      "deviceType": "DESKTOP",
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-15T10:30:00Z"
    }
  ],
  "totalCount": 1
}

get_test_case

Get detailed information about a specific test case by its ID.

Parameters:

• testCaseId (required): The test case ID to fetch (e.g., "tc_abc123")

Example:

{
  "testCaseId": "tc_xyz789"
}

create_test_case

Create a new automated test case for the site. Test cases verify specific user workflows and functionality.

Important: This tool creates test cases directly from the parameters you provide. The steps and goals are used exactly as-is without AI processing. Ensure you provide complete workflows including all prerequisites (login, navigation, etc.).

Workflow:

1. Call get_test_cases to check for duplicates
2. Ask user if authentication is needed
3. If needed, call get_credentials and ask user to choose
4. Create test case with complete workflow (login → navigation → test → verification)

Parameters:

• name (required): Test case name (max 8 words, descriptive)
• refinedTestCases (required): Array of test steps
• goals (required): Array of verifiable success criteria
• deviceType (optional): "DESKTOP" or "MOBILE" (default: "DESKTOP")
• siteCredentialsId (optional): Credential ID if test requires authentication
• userPrompt (optional): User prompt describing test intent

Example (authenticated test):

{
  "name": "Login and Access Settings",
  "refinedTestCases": [
    "Navigate to the login page",
    "In the username field, insert provided credentials",
    "In the password field, insert provided credentials",
    "Submit the login form",
    "Verify successful authentication",
    "Navigate to Settings page",
    "Verify Settings page loads correctly"
  ],
  "goals": [
    "User successfully authenticates",
    "Settings page is accessible"
  ],
  "deviceType": "DESKTOP",
  "siteCredentialsId": "cred_abc123"
}

Troubleshooting

"Command not found" or "Cannot find module"

• Ensure you have Node.js 18+ installed
• Try running npx @squidlerio/mcp-problems manually to verify it downloads correctly

"Failed to fetch problems" or "Authentication required"

1. Verify API key is set: Check that SQUIDLER_API_KEY is in your MCP configuration
2. Check API key is valid:
   • Log into Squidler web UI at https://squidler.io
   • Go to your site
   • Go to Settings → Developer
   • Verify the API key exists and hasn't been deleted
3. Check API URL: Make sure SQUIDLER_API_URL is set to https://api.squidler.io
4. Verify site has problems: Make sure your site has run at least one check with detected issues

"No MCP servers detected"

1. Verify your mcp.json file is in the correct location
2. Check the JSON syntax is valid (use a JSON validator)
3. Restart Claude Code after making configuration changes

"Empty response" or "No problems returned"

This is normal if:

• All problems have been resolved or dismissed
• Your site hasn't run any checks yet
• The API key is for a different site than you expect

To verify: Log into Squidler web UI and check that your site shows accessibility/quality issues.

See Also

• Model Context Protocol Documentation
• Squidler Documentation - Complete setup guides for MCP and Test Case API
• Squidler Web Application - Manage your sites and API keys