Metadata-Version: 2.4
Name: openresearch-mcp
Version: 0.1.1
Summary: Zero-auth multi-source research MCP server — web, GitHub, Hacker News, Stack Overflow, arXiv, Semantic Scholar, YouTube transcripts, and more.
Project-URL: Homepage, https://github.com/olanokhin/openresearch-mcp
Project-URL: Repository, https://github.com/olanokhin/openresearch-mcp
Project-URL: Bug Tracker, https://github.com/olanokhin/openresearch-mcp/issues
Author-email: Alex Anokhin <olanokhin@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai,arxiv,duckduckgo,github,llm,mcp,model-context-protocol,research,semantic-scholar,youtube
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: ddgs>=9.0
Requires-Dist: fastmcp>=2.0
Requires-Dist: pypdf>=5.0
Requires-Dist: requests>=2.32
Requires-Dist: youtube-transcript-api>=1.0
Provides-Extra: dev
Requires-Dist: httpx; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Description-Content-Type: text/markdown

# openresearch-mcp

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

## Tools

| Tool | Source | Auth |
|------|--------|------|
| `web_search` | DuckDuckGo | None |
| `read_url` | Any webpage | None |
| `read_pdf` | Any PDF / arXiv | None |
| `read_repo` | GitHub public repos | None (set `GITHUB_TOKEN` for 5k req/hr) |
| `search_hacker_news` | HN via Algolia API | None |
| `search_stackoverflow` | Stack Overflow API | None (set `STACKEXCHANGE_KEY` for higher limits) |
| `search_semantic_scholar` | Semantic Scholar API | None (set `SEMANTIC_SCHOLAR_KEY` for 1 req/sec) |
| `get_youtube_transcript` | YouTube captions | None |

## Quickstart

### Docker (recommended)

```bash
docker run -p 8000:8000 ghcr.io/yourusername/openresearch-mcp
```

With optional keys for higher limits:

```bash
docker run -p 8000:8000 \
  -e GITHUB_TOKEN=ghp_... \
  -e SEMANTIC_SCHOLAR_KEY=... \
  ghcr.io/yourusername/openresearch-mcp
```

### Local

```bash
pip install openresearch-mcp
openresearch-mcp
```

Or with uv:

```bash
uvx openresearch-mcp
```

### stdio (for Claude Desktop / Cursor)

```bash
MCP_TRANSPORT=stdio openresearch-mcp
```

Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "openresearch": {
      "command": "uvx",
      "args": ["openresearch-mcp"],
      "env": { "MCP_TRANSPORT": "stdio" }
    }
  }
}
```

## Connect via HTTP

Point your agent at `http://localhost:8000/mcp` (Streamable HTTP transport, MCP 1.1+).

## Known limitations

- **Reddit / Zenodo**: block unauthenticated requests — not included in v1
- **YouTube**: rate-limited by YouTube at scale; works for personal use
- **Semantic Scholar**: 100 req/5min without key; auto-falls back to DDG snippets on 429

## Roadmap

- [ ] Reddit OAuth (browser-based, no user key management)
- [ ] GitHub Device Flow login
- [ ] OpenAlex (zero-auth, 250M+ papers)
- [ ] NewsAPI support (optional key)
- [ ] PubMed / NCBI (optional key)

## License

MIT
