Broken Link Checker MCP Server

An MCP (Model Context Protocol) server that provides broken link checking capabilities using the broken-link-checker library.

Features

• Check Single Page Links: Scan all links on a single HTML page for broken links
• Check Entire Site: Recursively crawl and check all links across an entire website
• Detailed reporting including HTTP status codes, broken reasons, and link metadata
• Support for excluding external links and respecting robots.txt
• Two deployment modes: Local stdio or Remote HTTP/SSE

Installation

npm install

Deployment Options

Option 1: Local Usage (stdio transport)

Use index.js for local Claude Desktop integration.

Option 2: Remote Usage (HTTP/SSE transport)

Use server.js for remote deployment with ngrok or similar proxy services.

Usage with Claude Desktop (Local)

Step 1: Configure Claude Desktop

Add this server to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "broken-link-checker": {
      "command": "node",
      "args": ["/Users/davinoishi/Documents/Projects-AI/BLC/index.js"]
    }
  }
}

Make sure to update the path to match your actual installation directory.

Step 2: Restart Claude Desktop

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

Step 3: Use the Tools

The MCP server provides two main tools:

1. check_page_links

Check all links on a single HTML page.

Parameters:

• url (required): The URL of the page to check
• excludeExternalLinks (optional): If true, only check internal links (default: false)
• honorRobotExclusions (optional): If true, respect robots.txt (default: true)

Example:

Can you check the links on https://example.com for any broken links?

2. check_site

Recursively crawl and check all links across an entire website.

Parameters:

• url (required): The starting URL of the site to check
• excludeExternalLinks (optional): If true, only check internal links (default: false)
• honorRobotExclusions (optional): If true, respect robots.txt (default: true)
• maxSocketsPerHost (optional): Maximum concurrent requests per host (default: 1)

Example:

Can you crawl https://example.com and check all pages for broken links?

Remote Deployment with HTTP/SSE Transport

For remote deployments (e.g., deploying on a VPS and connecting via ngrok), use the HTTP/SSE server:

Step 1: Start the HTTP Server

# Start the HTTP/SSE server (default port 3000)
npm run start:http

# Or specify a custom port
PORT=8080 npm run start:http

The server will start on http://localhost:3000 (or your specified port).

Step 2: Expose with ngrok (or alternative)

# Install ngrok if you haven't already
npm install -g ngrok

# Expose your local server
ngrok http 3000

ngrok will provide you with a public URL like: https://abc123.ngrok.io

Step 3: Configure Claude Desktop for Remote Connection

Update your Claude Desktop configuration to use the HTTP/SSE transport:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "broken-link-checker": {
      "url": "https://your-ngrok-url.ngrok.io/sse"
    }
  }
}

Replace your-ngrok-url.ngrok.io with your actual ngrok URL.

Step 4: Test the Connection

1. Check the health endpoint: https://your-ngrok-url.ngrok.io/health
2. Restart Claude Desktop
3. Ask Claude to check links on a webpage

Environment Variables

You can configure the server using environment variables:

# Copy the example environment file
cp .env.example .env

# Edit .env with your settings
PORT=3000
HOST=0.0.0.0

Production Deployment

For production deployments, consider:

1. Use a process manager (PM2, systemd):

   npm install -g pm2
   pm2 start server.js --name broken-link-checker-mcp
   pm2 save
   pm2 startup
   

2. Use a reverse proxy (nginx, Caddy) for HTTPS

3. Add authentication if exposing publicly

4. Monitor logs and resource usage

Output Format

Both tools return JSON with the following structure:

{
  "summary": {
    "totalLinks": 100,
    "brokenLinks": 5,
    "workingLinks": 95
  },
  "brokenLinks": [
    {
      "url": "https://example.com/broken-page",
      "base": "https://example.com",
      "broken": true,
      "brokenReason": "HTTP_404",
      "http": {
        "statusCode": 404
      }
    }
  ]
}

Development

The main server code is in index.js. The server uses:

• @modelcontextprotocol/sdk for MCP protocol implementation
• broken-link-checker for link checking functionality

License

MIT