url-context-mcp

An MCP (Model Context Protocol) server that fetches web pages and extracts clean, AI-usable context from them. Runs over stdio transport.

It's designed for AI agents that need to:

• Read a web page as clean markdown (no boilerplate, no nav/footer noise)
• Discover links on a page (with filters) before deciding what to fetch next
• Search pages for specific text/code without reading the whole thing
• Do all of the above in a single call

Tools

Tool	What it does
fetch_url	Fetch a URL → readable article as markdown (or text/html/readable). Optional includeLinks=false, maxChars.
extract_links	Get all links from a URL or raw HTML. Optional regex filter, sameDomainOnly, limit. Resolves relative links correctly.
search_content	Regex search a URL's content; returns matches with surrounding context.
fetch_and_search	One-shot combo: returns content and links and search matches in a single call. The most token-efficient way to understand + navigate a page.
fetch_image	Fetch an image by URL (absolute or relative to a base page) and return it as base64 image content the model can see. Resolves relative URLs from page extraction (e.g. images/logo.png against the page that referenced it). Optional maxSizeKB guard (default 512 KB).

All tools accept either a url (server fetches it) or raw html (you provide the markup), so they're composable with other fetchers too.

Installation (copy-paste into your MCP client config)

{
  "mcpServers": {
    "url-context": {
      "command": "npx",
      "args": ["-y", "url-context-mcp"]
    }
  }
}

That's it. npx -y downloads and runs the server on first use; no separate install step needed. Requires Node.js 18+.

Why it's the best design for an AI agent

• Readability-first: defaults to Mozilla Readability extraction so the agent gets the article, not the chrome. Reduces tokens and irrelevance.
• One-call combo: fetch_and_search returns content + links + matches together — fewer round trips when an agent wants to "understand this page and find X on it".
• Link discovery before prefetch: extract_links lets an agent survey a page's destinations and pick the right one to fetch, instead of guessing or fetching everything.
• Regex search with context: agents can locate an error string, an API endpoint, a version number, etc. on a page with bounded context windows.
• No browser, no head: pure HTTP + jsdom. Fast, sandboxed, works anywhere Node runs. No Playwright/Chromium dependency bloat.
• Sane defaults + truncation: maxChars, limit, maxMatches keep responses bounded so context windows don't blow up.

Local development

npm install
node index.js          # run the stdio server
npm pack               # build the publishable tarball

Changelog

1.2.0

• New tool: fetch_image. Resolves an image URL (absolute, or relative to a baseUrl) and returns it as an MCP image content block (base64 with a mimeType derived from the response Content-Type header, falling back to the URL extension). Lets the model actually see images found in pages marked up in markdown. Optional maxSizeKB (default 512 KB) protects the context window from oversized payloads. MIME fallback map covers png/jpg/jpeg/gif/webp/svg/bmp/avif/ico.
• Server version bumps to 1.2; user-agent string updated accordingly.

1.1.0

• Preserve dropped headings in extracted content. Mozilla Readability strips the page <h1>/title from its content on minimal pages (e.g. example.com: the # Example Domain heading was never returned by fetch_url, and search_content therefore couldn't find "Example Domain"). We now detect headings present in the raw body but missing from Readability's cleaned HTML and re-prepend them, so the page title is always part of the returned markdown/text and is searchable.
• search_content raw-HTML fallback. When a search of the converted (markdown/text) content finds zero matches and raw HTML is available, the tool re-runs the search against the stripped raw text as a safety net. The result flag notes when the fallback path was used ((raw-HTML fallback) in the header).
• Misc: user-agent string bumped to 1.1.

License

MIT