Content
# claude-research-agent
> Multi-source research agent for **Claude Code**: an MCP server (arXiv, OpenAlex, GitHub,
> Hacker News, X/Grok) plus a `/research` skill that fans out over subtopics and writes a
> structured, citation-rich report in Markdown and a clean readable HTML.
Plugin for [Claude Code](https://claude.com/claude-code), which turns it into
a research agent: searches scientific databases, code, and social networks, checks and aggregates sources into
**structured report with clickable citations** (Markdown + HTML).
## What's Inside
- **MCP Server** (`server/`) with five tool-sources:
| Tool | Source | Key |
|---|---|---|
| `search_arxiv` | ML/AI preprints (arXiv) | — |
| `search_openalex` | scientific works + citations (OpenAlex, all disciplines) | — |
| `search_github` | repositories/code | optional `GITHUB_TOKEN` or `gh auth token` |
| `search_hackernews` | tech community discussions | — |
| `search_x` | X/Twitter posts via xAI Grok | `XAI_API_KEY` (paid) |
- **`/research` Skill** (`skills/research/`): topic decomposition → fan-out over subtopics →
synthesis → report with sections and citations → HTML generation from Markdown. Choosing the volume
(small/medium/large/extra large) scales the search width.
Web search and report writing are done by Claude Code itself — this plugin provides sources and a scenario.
## Requirements
- [Claude Code](https://claude.com/claude-code)
- [`uv`](https://docs.astral.sh/uv/) (Python environment manager) — MCP server is launched through it
- (optional) `gh` CLI — then GitHub search is authorized automatically
- (optional) xAI key with credits — for X search
## Installation (as a plugin)
```bash
git clone https://github.com/<you>/claude-research-agent
cd claude-research-agent
# register as a local plugin in Claude Code:
claude plugin install ./claude-research-agent # or add path to marketplace config
```
After installation, restart `claude`, run `/mcp` — **research** server with 5 tools should appear,
and `/research` — in the skills list.
> MCP server will install dependencies via `uv` on the first launch (see `server/pyproject.toml`).
## Keys (optional)
Copy `server/.env.example` → `server/.env` and fill in the necessary:
- `XAI_API_KEY` — enables `search_x` (xAI Grok, paid; **per call**, ~$0.2).
- `GITHUB_TOKEN` — increases GitHub limits (if no `gh` CLI).
- `OPENALEX_EMAIL` — "polite pool" OpenAlex (optional).
Without any keys, **arXiv, OpenAlex, GitHub, Hacker News** work immediately.
## Usage
In Claude Code chat:
```
/research
```
or simply: "make a deep research on topic X, report with citations". The skill will ask for volume,
agree on the mode (fan-out/inline), collect sources, and save `./research-reports/<topic>.md`
+ `.html` with clickable links to each source (including direct links to X posts).
## Cost
Free everything except X. `search_x` is charged **per call** (not per post),
so the skill collects X in a separate "wave": 1–3 broad calls per report (~$0.2–0.7).
## Security
`.env` with keys **is not committed to git** (see `.gitignore`). Don't publish your keys.
## License
MIT — see [LICENSE](LICENSE).
