AtlasForge WebProxy

Self-hosted web search/fetch proxy plus stdio MCP server for AI agents. It provides Brave-backed search, page fetch with retries and browser-like user-agent fallback, old.reddit hardening, response caching, paper PDF fetch, image search/download, and SSRF guards.

Quickstart

./install.sh
mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/atlasforge-webproxy"
$EDITOR "${XDG_CONFIG_HOME:-$HOME/.config}/atlasforge-webproxy/config.env"
chmod 600 "${XDG_CONFIG_HOME:-$HOME/.config}/atlasforge-webproxy/config.env"

Set BRAVE_API_KEY in that file. Get a key at https://brave.com/search/api/. Without a key, the proxy falls back to DDG/DDGS where available.

Run directly:

.venv/bin/python -m atlasforge_webproxy.service --host 127.0.0.1 --port 8765
curl http://127.0.0.1:8765/health

Wire MCP into a client:

{
  "mcpServers": {
    "atlasforge-web-proxy": {
      "command": "/path/to/AtlasForge-WebProxy/.venv/bin/python",
      "args": ["-m", "atlasforge_webproxy.mcp_server"],
      "env": {}
    }
  }
}

Config

Priority: environment variables, then ${XDG_CONFIG_HOME:-~/.config}/atlasforge-webproxy/config.env, then defaults. For migration, ~/.config/atlasforge/web-proxy.env is read only when the new file does not exist, and a deprecation warning is logged.

See config.env.example for the full list, including user-agent and size-limit knobs.

systemd

./install.sh creates .venv, installs the package, copies config.env.example if no config exists, installs ~/.config/systemd/user/atlasforge-webproxy.service, and runs systemctl --user daemon-reload.

It does not enable or start the service unless passed --start:

./install.sh --start
systemctl --user status atlasforge-webproxy.service

Tests

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

Use an unused non-8765 port for live smoke tests:

ATLASFORGE_WEB_PROXY_PORT=8799 .venv/bin/python -m atlasforge_webproxy.service --port 8799