The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Odysseus Web MCP listing page.
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: web_search to discover sources and web_fetch 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.


Requirements: Python 3.11+ and uv.
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:
The launcher automatically uses the package's .venv. State defaults to
~/.local/share/odysseus-web-mcp; set WEB_MCP_DATA_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.
web_searchUse it to discover sources for a focused question. It accepts one to three queries plus optional mode, vertical, and freshness controls.
The response contains ranked URLs, titles, snippets, provider attempts,
cache state, a plain-text display projection, and an evidence_id. A host can
take any returned URL directly into web_fetch.
web_fetchUse it to read a known public URL or a bounded batch of URLs.
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.
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.
The MCP returns a text content block containing structured JSON:
The agent takes the returned URL and calls the second tool:
The MCP returns bounded, extracted evidence:
The agent can now answer the user from the extracted content, preserve the
evidence_id for traceability, and continue with another web_fetch using a
returned cursor if the page was longer than the output budget.
All persistent state is rooted under WEB_MCP_DATA_DIR. The package has no
runtime imports from Odysseus and no access to its credentials, database,
memory, browser profiles, scheduler, or agent loop.
Read the full local system design in
docs/TECHNICAL_DESIGN.md, and see how the GIFs
were recorded in docs/INTERACTIVE_DEMO.md.
The default provider chain is:
Configure it with WEB_MCP_SEARCH_PROVIDER_CHAIN. Optional credentials are
DATA_BRAVE_API_KEY, TAVILY_API_KEY, and SERPER_API_KEY. Copy
.env.example as a reference, but keep secrets in the host
environment rather than committing them.
The optional browser path is disabled by default:
The server is published in the official MCP Registry
under io.github.AceAtDev/odysseus-web-mcp.
For Claude Desktop and other MCPB-compatible clients, download the validated
MCPB release bundle
from the v0.1.0 GitHub Release.
The bundle uses the uv runtime to resolve the declared Python dependencies
without shipping a machine-specific virtual environment.
The project has a focused test suite and a live qualification runner:
The live qualification runs 10 searches and 10 fetches through the real MCP
launcher with disposable state. The latest verification record is in
VERIFICATION.md.
To re-record the terminal previews from fresh live calls (requires
ImageMagick's convert command):
Each GIF is intentionally under ten seconds and shows a real MCP handshake and result shape, not a static product mockup.
This package is a retrieval primitive, not an agent loop, general-purpose crawler, scheduler, memory store, browser-profile manager, or credential vault. It is designed to be downloaded and connected as an independent MCP server.
This is the standalone extraction workspace for the Odysseus web search/fetch
capability. See MIGRATION_MAP.md for the source-to-module
mapping and VERIFICATION.md for the current evidence-based
status.