Openresearch

PyPI version Python versions License CI MCP Registry

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_... [email protected] uvx openresearch-mcp

Or in Claude Desktop config:

{
  "mcpServers": {
    "openresearch": {
      "command": "uvx",
      "args": ["openresearch-mcp", "--stdio"],
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "OPENALEX_EMAIL": "[email protected]"
      }
    }
  }
}

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