openresearch-mcp

Zero-auth cross-domain research MCP server. Works with Claude Desktop, Cursor, OpenCode, Open WebUI, or any MCP-compatible agent — no API keys required.

Tools

Context footprint

Tokens injected into the agent context on every request (the tools/list definition of each tool, plus the server instructions):

Measured with tiktoken o200k_base (GPT-4o / o-series encoding), offline. Claude's tokenizer differs by ~±10-15%. Regenerate with uv run python scripts/context_cost.py --write; CI fails if this block drifts.

Install

From the MCP Registry (recommended for Claude Desktop / Cursor)

The server is listed on the official MCP Registry as io.github.olanokhin/openresearch-mcp. Registry-aware clients can discover and install it without manual config — search for openresearch-mcp in your client's MCP browser.

From PyPI

# Zero install, always isolated — recommended for manual use
uvx openresearch-mcp

# Or install globally
pip install openresearch-mcp
openresearch-mcp

By default the server starts on http://127.0.0.1:8000/mcp (Streamable HTTP, MCP 1.1+) — bound to loopback so it is not exposed to your local network. To expose it (e.g. in a container or behind a gateway), bind all interfaces explicitly:

# Custom port
uvx openresearch-mcp --port 9000

# Bind all interfaces (only behind an auth/rate-limit gateway)
uvx openresearch-mcp --host 0.0.0.0 --port 9000

Note: when binding beyond loopback, put an auth/rate-limit gateway in front. The server is zero-auth by design, and read_url/read_pdf fetch arbitrary URLs (private/link-local/loopback ranges are blocked to prevent SSRF, but rate limiting is your responsibility).

Update

# uvx
uvx --refresh openresearch-mcp

# pip
pip install --upgrade openresearch-mcp

Connect to an MCP client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json
(Windows: %APPDATA%\Claude\claude_desktop_config.json)

{
  "mcpServers": {
    "openresearch": {
      "command": "uvx",
      "args": ["openresearch-mcp", "--stdio"]
    }
  }
}

Restart Claude Desktop after saving. The server runs in stdio mode — no port needed.

Cursor

Create or edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "openresearch": {
      "command": "uvx",
      "args": ["openresearch-mcp", "--stdio"]
    }
  }
}

HTTP agents (OpenCode, Open WebUI, custom)

Start the server:

uvx openresearch-mcp
# or: openresearch-mcp

Point your agent at:

http://localhost:8000/mcp

Optional env vars

All tools work without any keys. Set these to increase rate limits:

Example with keys:

GITHUB_TOKEN=ghp_... OPENALEX_EMAIL=you@example.com uvx openresearch-mcp

Or in Claude Desktop config:

{
  "mcpServers": {
    "openresearch": {
      "command": "uvx",
      "args": ["openresearch-mcp", "--stdio"],
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "OPENALEX_EMAIL": "you@example.com"
      }
    }
  }
}

Health check

When running in HTTP mode, check which sources are reachable:

curl http://localhost:8000/health

{
  "status": "ok",
  "sources": {
    "duckduckgo":    { "status": "ok", "latency_ms": 173 },
    "github":        { "status": "ok", "latency_ms": 101 },
    "hacker_news":   { "status": "ok", "latency_ms": 308 },
    "stackoverflow": { "status": "ok", "latency_ms": 247 },
    "openalex":      { "status": "ok", "latency_ms": 412 },
    "youtube":       { "status": "ok", "latency_ms": 320 }
  }
}

status is "ok", "degraded" (some sources down), or "down" (all unreachable). HTTP 200 / 503.

Known limitations

• Reddit / Zenodo: block unauthenticated scraping — not included
• YouTube: rate-limited at scale; works well for personal/low-volume use
• Weather (Open-Meteo): data is licensed CC BY 4.0 and free for non-commercial use up to ~10,000 requests/day. Commercial use requires Open-Meteo's paid plan or self-hosting — embedding get_weather_forecast in a commercial product without one inherits a license obligation. Attribution to Open-Meteo is required.
• PDF parsing: read_pdf parses untrusted PDFs in-process (with download-size and page caps). Fine for personal/low-volume use; a public high-volume deployment should isolate parsing in a subprocess with CPU/memory limits.

Roadmap

• Reddit OAuth (browser-based, no user key management)
• GitHub Device Flow login
• PubMed / NCBI (optional key)
• NewsAPI support (optional key)

Security

openresearch-mcp was reviewed and hardened using agent-security-skill, an OWASP-aligned AI agent security review skill developed by the maintainer.

That review directly led to concrete hardening in this server: SSRF-resistant URL fetching, untrusted-content framing for tool outputs, bounded downloads, pinned GitHub Actions, dependency major-version caps, and regression tests for security-sensitive behavior.

See the hardening notes and current security posture in SECURITY.md.

License

Apache 2.0