Odysseus Web MCP server

Odysseus Web MCP — Secure Web Search and Fetch Server for AI Assistants

Odysseus Web MCP is a standalone Model Context Protocol (MCP) server for safe public-web search and URL fetching. It runs locally over stdio and gives MCP-compatible AI assistants two retrieval tools: websearch to discover sources and webfetch to retrieve and extract public URLs.

Built for clients such as Claude Code, Cursor, and Codex, it combines search-provider fallback, readable HTML/PDF/text extraction, optional JavaScript rendering, and SSRF protections including DNS validation and redirect rechecks.

Features

• Search the public web with provider fallback and ranked, attributed sources.
• Fetch and extract HTML, PDF, and text content from public URLs.
• Protect against SSRF with public-network checks, DNS validation, and redirect revalidation.
• Return bounded, evidence-oriented output with cursors, quality signals, and discovered links.
• Optionally render JavaScript-heavy pages in isolated Playwright.

Install in minutes

Requirements: Python 3.11+ and uv.

# after downloading/extracting this folder (or cloning your copy)
cd odysseus-web-mcp
uv venv .venv
uv pip install -e '.[dev]'
./run-web-mcp.sh

The server communicates over stdio, so it does not open a web port and does not need to be installed into your host application's Python environment. Register the absolute launcher path in your MCP client:

{
  "name": "odysseus-web-mcp",
  "command": "/absolute/path/to/odysseus-web-mcp/run-web-mcp.sh",
  "args": [],
  "cwd": "/absolute/path/to/odysseus-web-mcp"
}

The launcher automatically uses the package's .venv. State defaults to ~/.local/share/odysseus-web-mcp; set WEBMCPDATA_DIR to place it elsewhere. No API key is required for the default fallback path, though Brave, Tavily, and Serper keys can be added when you want those providers.

The two tools

web_search

Use it to discover sources for a focused question. It accepts one to three queries plus optional mode, vertical, and freshness controls.

{
  "queries": "Model Context Protocol Python SDK",
  "mode": "discovery",
  "vertical": "general"
}

The response contains ranked URLs, titles, snippets, provider attempts, cache state, a plain-text display projection, and an evidenceid. A host can take any returned URL directly into webfetch.

web_fetch

Use it to read a known public URL or a bounded batch of URLs.

{
  "url": "https://example.com",
  "focus": "the page's purpose",
  "render": "auto"
}

It returns extracted text, title and document kind, content quality, link discovery, redirect history, HTTP status, truncation/continuation metadata, and an evidence_id. Private and special-use destinations are rejected before transport by default.

Example: how an agent uses the MCP

An agent normally uses the tools as a two-step retrieval loop: search first, then fetch the source it wants to inspect. The payloads below show the shape of a real MCP interaction; IDs and result text are abbreviated for readability.

1. Agent searches for sources

{
  "name": "web_search",
  "arguments": {
    "queries": "official Model Context Protocol architecture",
    "mode": "grounding",
    "vertical": "general"
  }
}

The MCP returns a text content block containing structured JSON:

Shortened. The full README is on GitHub.