link-check-lite

Free. No API key. Runs on your own computer. It only visits the links you give it.

A tool that checks a list of links. It tells you which ones work, which are broken, and where redirects end up. Need sitemaps, speed checks, sketchy-domain warnings or CSV reports? The paid version does that: link-check on Gumroad

MIT license. Python 3.10 or newer, on Windows, Mac and Linux. The checker itself uses only Python's built-in tools.

Install

pip install link-check-lite

Or use pipx, which keeps it in its own space:

pipx install link-check-lite

Want the newest code from GitHub instead?

pip install git+https://github.com/tidybytetools/link-check-lite

Related MCP server: MCP Web Tools

Use it

Put your links in a text file, one per line. Lines that start with # are skipped.

link-check-lite links.txt
link-check-lite links.txt -w 3 --timeout 20   # gentler and more patient

Example run:

OK   200 https://example.com/
OK   200 https://httpbin.org/redirect/2  -> https://httpbin.org/get (2 redirects)
FAIL 404 https://example.com/old-page
FAIL --- https://no-such-site.example  ([Errno -2] Name or service not known)

4 checked, 2 ok, 2 broken

Exit code is 0 when every link works and 1 when any link is broken, so it works in a cron job or CI.

When you run it in a terminal it ends with one short line about the paid version. --quiet turns it off, and it never shows when output is piped.

Known limits

• Some sites block bots. They may answer 403 or 429 even when the page opens fine in a browser.

• No JavaScript. Redirects done with JavaScript are not followed.

• Text file only. No CSV input, no sitemaps, and results print to the screen.

• No robots.txt and no per-site rate limit. It checks 5 links at a time with a small pause. Don't point it at thousands of pages on one site.

• Not a safety check. It does not tell you if a link is a scam.

Lite vs paid

How it compares to other free tools

All of these are free. Pick what fits you.

If you need to crawl a big site or check links inside Markdown files, lychee and linkchecker are great.

Use it with your AI app (MCP)

There is a small free MCP server built in. It gives your AI app one tool, check_links. No API key or account is needed. It needs uv, which gives you the uvx command.

Run it by hand to check it starts (it waits quietly for an app to talk to it):

uvx --from link-check-lite link-check-lite-mcp

Shorter way to start the same server: uvx link-check-lite mcp.

Pick your app below and copy the block. Restart the app after you save.

Claude Desktop

Open Settings > Developer > Edit Config. That opens claude_desktop_config.json. Add this:

{
  "mcpServers": {
    "link-check-lite": {
      "command": "uvx",
      "args": ["--from", "link-check-lite", "link-check-lite-mcp"]
    }
  }
}

If Claude says it can't find uvx, run which uvx (Mac/Linux) or where uvx (Windows) and put that full path in "command".

Cursor

Put the same block in ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "link-check-lite": {
      "command": "uvx",
      "args": ["--from", "link-check-lite", "link-check-lite-mcp"]
    }
  }
}

VS Code

VS Code uses servers, not mcpServers. Put this in .vscode/mcp.json in your project, or run MCP: Open User Configuration to use it everywhere:

{
  "servers": {
    "link-check-lite": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "link-check-lite", "link-check-lite-mcp"]
    }
  }
}

Or add it with one command:

code --add-mcp '{"name":"link-check-lite","type":"stdio","command":"uvx","args":["--from","link-check-lite","link-check-lite-mcp"]}'

Cline

In the Cline panel, click the MCP Servers icon, open Configure, then click Configure MCP Servers. Add this inside mcpServers:

{
  "mcpServers": {
    "link-check-lite": {
      "command": "uvx",
      "args": ["--from", "link-check-lite", "link-check-lite-mcp"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Codex

One command:

codex mcp add link-check-lite -- uvx --from link-check-lite link-check-lite-mcp

Or add this to ~/.codex/config.toml:

[mcp_servers.link-check-lite]
command = "uvx"
args = ["--from", "link-check-lite", "link-check-lite-mcp"]

Gemini CLI

This repo is also a Gemini CLI extension. Install it with:

gemini extensions install https://github.com/tidybytetools/link-check-lite

Tool: check_links(urls, timeout=10.0). Send up to 200 links. It returns one result per link.

Use it in GitHub Actions

Link Check Lite is on the GitHub Marketplace. Check your links every time you push. Put your links in a text file, one per line. Then add this step to a workflow:

- uses: actions/checkout@v7
- uses: tidybytetools/link-check-lite@v1
  with:
    file: links.txt          # one link per line
    # fail-on-broken: "false"  # pass even if some links are broken

@v1 always points to the newest 1.x release. To stay on one exact release, use a full tag like @v1.1.2.

The step fails if any link is broken. It also writes a short report to the run summary. It installs link-check-lite from PyPI. Your links are sent only to the sites they point to.

Inputs

Outputs

Use it from Python

from link_check_lite import check_link
print(check_link("https://example.com"))
# {'url': 'https://example.com', 'status': 200, 'ok': True, 'final_url': 'https://example.com', 'redirects': [], 'error': None}

For AI agents

• Use when: you need to know if web links work and where their redirects end up.

• Don't use when: you need to know if a link is safe, need a whole site crawled, or need speed or https checks. Use the paid version for those.

• Input: a list of http(s) URLs (max 200 per MCP call), plus an optional timeout in seconds.

• Output: a list of {url, status, ok, final_url, redirects, error}. status is null when the link could not connect. ok is true for 200-399. redirects lists each hop as "CODE url".

• CLI exit code is 0 when all links work and 1 when any link is broken or on error. See also llms.txt.

Tests

pip install "mcp>=1.10,<2"
python3 -m unittest discover tests

The tests use a tiny local web server, so they don't need the internet.

License

MIT. See LICENSE.