openresearch-mcp

![PyPI version](https://pypi.org/project/openresearch-mcp/) ![Python versions](https://pypi.org/project/openresearch-mcp/) ![License](LICENSE) ![CI](https://github.com/olanokhin/openresearch-mcp/actions/workflows/ci.yml) ![MCP Registry](https://registry.modelcontextprotocol.io)

Zero-auth, security-hardened research MCP for cross-domain agents.

Give Claude, Cursor, OpenCode, Open WebUI, or any MCP-compatible agent a full research stack — web search, academic papers, PDFs, GitHub repos, news, macro & finance data, SEC filings, biomedical literature, Bluesky, and YouTube — with no API keys to manage. 22 tools, one install.

Why

Research agents are only as good as the sources they can reach. But every extra source usually means another API key, another signup, another quota to babysit — and more attack surface.

openresearch-mcp is built for local-first agents that need useful public data now, with safer defaults:

No logins, no keys — every tool works out of the box; optional env vars only raise rate limits.
Hardened by design — loopback-bound by default, SSRF-filtered URL fetching, prompt-injection-aware extraction, bounded downloads, graceful failures. Security-reviewed against OWASP for AI agents.
Cheap in context — the whole 22-tool surface is a measured ~6.2K tokens (~3% of a 200K window), and the number is generated by a script in the repo, not guessed.

What you can do

The value isn't 22 tools in isolation — it's chaining them into one cross-domain research pass:

Company research → search_sec_filings / get_company_financials → search_news → read_repo → read_url
Academic deep-dive → search_openalex → search_europepmc → read_pdf
Macro & country context → search_indicators → get_country_indicator → get_fx_rate → get_historical_weather

Quickstart

uvx openresearch-mcp --stdio

Point any MCP client at it (Claude Desktop, Cursor, or an HTTP agent — see Connect) and ask something cross-domain:

"Pull Apple's latest annual revenue from its SEC filings, then find recent news on its AI strategy."

The agent chains get_company_financials → search_news for you — no keys, no setup.

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).

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

Tools

The ~Tok column is each tool's full definition (name + description + JSON input schema, as sent in tools/list) — injected into the agent context on every request.

| Tool | Source | Notes | ~Tok | | ---- | ------ | ----- | ---: | | web_search | DuckDuckGo | Optional site= param to scope to a domain (e.g. arxiv.org) | 251 | | read_url | Any webpage | Strips nav/scripts, returns clean text | 164 | | read_pdf | Any PDF or arXiv | Accepts /abs/, /pdf/, /html/ arXiv URLs interchangeably | 181 | | read_repo | GitHub public repos | README + file tree + key docs; set GITHUB_TOKEN for 5k req/hr | 211 | | search_hacker_news | HN via Algolia | Story search with points + comment counts | 206 | | search_stackoverflow | Stack Overflow API | Set STACKEXCHANGE_KEY for higher quota | 212 | | search_openalex | OpenAlex | 250M+ works, zero rate limiting; set OPENALEX_EMAIL for polite pool | 231 | | get_youtube_transcript | YouTube captions | Accepts full URLs, youtu.be/ links, shorts, or bare video IDs | 194 | | get_current_date | Server clock | Current UTC date/time — anchors relative requests ("last 30 days") instead of guessing | 240 | | get_weather_forecast | Open-Meteo | Current conditions + up to 16-day forecast by place name; no key. See licensing note below | 229 | | get_historical_weather | Open-Meteo | Climate series since 1940 for a place + date range, aggregated monthly/yearly; no key. See licensing note below | 328 | | search_indicators | World Bank | Find an indicator code by keyword ("GDP", "migration"); feed into get_country_indicator | 240 | | get_country_indicator | World Bank | Yearly socio-economic series (GDP, population, inflation, migration, life expectancy…) by country + code; no key | 338 | | get_fx_rate | Frankfurter (ECB) | Currency rates: latest, a historical date, or a date-range series (downsample week/month); no key | 367 | | get_crypto_price | CoinGecko | Crypto price (current or daily history) by coin id/symbol vs a quote currency; no key | 284 | | search_news | GDELT | Fresh global news on a topic (multilingual); returns articles to feed into read_url; no key (rate-limited ~1/5s) | 481 | | search_europepmc | Europe PMC | Biomedical/life-science papers; flags open-access and gives a PDF URL to feed into read_pdf; no key | 264 | | search_bluesky_users | Bluesky | Find researcher/dev profiles by name, handle, or bio; no key | 227 | | get_bluesky_profile | Bluesky | Full bio + follower/post counts for a handle; no key | 200 | | read_bluesky_feed | Bluesky | A user's recent original posts (reposts/replies filtered); no key | 228 | | get_company_financials | SEC EDGAR | Annual revenue, earnings, assets for a US-listed company by ticker (10-K filings); no key (set SEC_USER_AGENT for heavy use) | 233 | | search_sec_filings | SEC EDGAR | Full-text search of filings (10-K/10-Q/8-K) by keyword/company; returns a document URL to feed into read_url/read_pdf; no key | 300 | | All 22 tool definitions | | | 5,609 | | Server instructions | | selection guide + chaining recipes | 815 | | Total per request | | ≈ 3% of a 200K context window | 6,424 |

_Tokens measured with tiktoken o200k_base (GPT-4o / o-series encoding), offline; Claude's tokenizer differs by ~±10-15%. This table is generated — run uv run python scripts/context_cost.py --write; CI fails if it drifts._

Optional env vars

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

| Variable | Effect | | -------- | ------ | | GITHUB_TOKEN | GitHub: 60 → 5,000 req/hr | | OPENALEX_EMAIL | OpenAlex polite pool (higher limits) | | STACKEXCHANGE_KEY | Stack Overflow: higher daily quota | | SEC_USER_AGENT | Your contact (e.g. email) for SEC EDGAR fair-access; a default is used otherwise |

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"
      }
    }
  }
}

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.

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 },
    "worldbank":     { "status": "ok", "latency_ms": 296 },
    "frankfurter":   { "status": "ok", "latency_ms": 184 },
    "europepmc":     { "status": "ok", "latency_ms": 356 },
    "bluesky":       { "status": "ok", "latency_ms": 152 },
    "youtube":       { "status": "ok", "latency_ms": 320 }
  }
}

status is "ok", "degraded" (some sources down), or "down" (all unreachable). HTTP 200 / 503. /health is a lightweight upstream reachability sample, not a per-tool status matrix. Rate-limited or policy-sensitive sources (GDELT, SEC, CoinGecko, etc.) are checked when their tools are called.

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)

License

Apache 2.0

openresearch-mcp