beacon

A zero-config web search MCP server for any MCP client (opencode, Claude Desktop, Cursor, etc.).

Gives your local models the ability to search the web and read page content — no API keys, no Docker, no setup beyond pip install.

What it gives you

Two MCP tools:

Tool	Description
`beacon_search(query, max_results=5)`	Web search via DuckDuckGo. Returns `{title, url, snippet}` hits.
`beacon_fetch(url, max_chars=8000)`	Fetches a URL and returns its main readable text (HTML-stripped, boilerplate removed).

git clone <your-fork-url> beacon
cd beacon
python3 -m venv .venv
.venv/bin/pip install -e .

Add to your opencode.json:

{
  "mcp": {
    "beacon": {
      "type": "local",
      "command": ["/absolute/path/to/beacon/.venv/bin/beacon-mcp"]
    }
  }
}

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "beacon": {
      "command": "/absolute/path/to/beacon/.venv/bin/beacon-mcp"
    }
  }
}

.venv/bin/beacon search "python async patterns"
.venv/bin/beacon fetch https://example.org

Variable	Default	Purpose
`BEACON_TIMEOUT`	`15`	HTTP timeout (seconds) for fetch
`BEACON_USER_AGENT`	Firefox-like string	User-Agent for outbound requests
`BEACON_LOG_LEVEL`	`INFO`	Logging verbosity

No state is written to disk. No database. No API keys required.

.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest -v

MIT.