io.github.JustinBeckwith/linkinator-mcp

Linkinator MCP Server

A Model Context Protocol (MCP) server that provides link checking capabilities using linkinator. This allows AI assistants like Claude to scan webpages and local files for broken links.

Features

• Comprehensive Link Checking: Scan websites and local files for broken links
• Recursive Crawling: Follow links within the same domain
• Multiple Content Types: Check links in HTML, CSS, and Markdown files
• Fragment Validation: Verify anchor links and URL fragments
• Flexible Configuration: Extensive options for timeouts, retries, SSL, and more
• Detailed Reporting: Get status codes, broken links grouped by error type, and parent page information

Quick Setup (Automatic)

The easiest way to get started is using the install-mcp tool, which automatically configures linkinator-mcp for Claude Desktop, Claude Code, Cursor, Cline, and other MCP clients:

npx install-mcp linkinator-mcp --client claude

This handles all configuration automatically. Restart your Claude client after installation.

Manual Configuration

If you prefer to configure the server manually, you can edit your MCP client's configuration file directly.

Claude Code

macOS/Linux

Edit ~/.config/claude-code/config.json:

{
  "mcpServers": {
    "linkinator": {
      "command": "npx",
      "args": ["linkinator-mcp"]
    }
  }
}

Windows

Edit %APPDATA%\claude-code\config.json:

{
  "mcpServers": {
    "linkinator": {
      "command": "npx",
      "args": ["linkinator-mcp"]
    }
  }
}

Alternative: Global Installation

If you prefer to install the package globally first with npm install -g linkinator-mcp, you can simplify the configuration:

{
  "mcpServers": {
    "linkinator": {
      "command": "linkinator-mcp"
    }
  }
}

Claude Desktop

macOS/Linux

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

{
  "mcpServers": {
    "linkinator": {
      "command": "npx",
      "args": ["linkinator-mcp"]
    }
  }
}

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "linkinator": {
      "command": "npx",
      "args": ["linkinator-mcp"]
    }
  }
}

Restart Your Client

After updating the configuration, restart your Claude client for the changes to take effect.

Usage Examples

Once configured, you can ask Claude to check links on any webpage or local file. Here are some example prompts:

Basic Link Checking

Check all the links on https://example.com

Recursive Scanning

Scan https://example.com recursively and check all links on the same domain

Local File Checking

Check the links in /path/to/my/documentation/index.html

Advanced Options

Check https://example.com with the following options:
- Recurse through all pages
- Check CSS for URLs
- Validate anchor fragments
- Skip links to google.com and facebook.com
- Use a 10 second timeout

Available Options

The scan_page tool supports all of linkinator's CLI options:

Required

• path (string): URL or local file path to scan

Connection Settings

• concurrency (number): Number of simultaneous connections (default: 100)
• port (number): Server port for local scanning (random port by default)
• timeout (number): Request timeout in milliseconds (0 = no timeout)

Crawling Behavior

• recurse (boolean): Follow links recursively on the same domain
• serverRoot (string): Custom disk location where the server starts
• directoryListing (boolean): Auto-serve directory index files
• cleanUrls (boolean): Enable extensionless link resolution (e.g., /about → /about.html)

Content Parsing

• markdown (boolean): Parse and scan markdown files
• checkCss (boolean): Extract and validate URLs in CSS properties
• checkFragments (boolean): Validate URL anchor identifiers

Filtering & Customization

• linksToSkip (string[]): URL patterns to exclude (regex strings)
• userAgent (string): Custom user agent header

Retry Logic

• retry (boolean): Retry HTTP 429 responses with retry-after header
• retryErrors (boolean): Retry 5xx errors
• retryErrorsCount (number): Retry attempt limit
• retryErrorsJitter (number): Random delay between retries in milliseconds

SSL & Security

• allowInsecureCerts (boolean): Accept invalid SSL certificates

Output Format

The tool returns a formatted report showing:

Linkinator Scan Results for: https://example.com

Summary:
  Status: ✓ PASSED / ✗ FAILED
  Total Links: 150
  OK: 145
  Broken: 5
  Skipped: 0

Broken Links:

  Status 404:
    - https://example.com/missing-page
      Found on: https://example.com/index.html
    - https://example.com/old-blog-post
      Found on: https://example.com/blog.html

  Status 500:
    - https://api.example.com/endpoint
      Found on: https://example.com/docs.html

Troubleshooting

Server Not Appearing in Claude Code

1. Check that the path in config.json is absolute, not relative
2. Verify the build directory exists: ls /path/to/linkinator-mcp/build/index.js
3. Check Claude Code logs for errors
4. Ensure Node.js is in your PATH

Permission Errors

If you get permission errors on macOS/Linux:

chmod +x /path/to/linkinator-mcp/build/index.js

Port Already in Use

If scanning local files and getting port errors, try specifying a port:

Check /path/to/files with port 9000

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details on how to get started.

License

MIT

Related Projects

• linkinator - The underlying link checking library
• MCP Servers - Collection of MCP server implementations
• Claude Code - AI coding assistant that uses MCP

Author

Justin Beckwith <justin.beckwith@gmail.com>

Acknowledgments

Built with the Model Context Protocol SDK.