grad-agent
Autonomous MCP agent for grad school applications: prof discovery, cold emails, SOP, tracking.
Open source Open in the app JSON README (API)
About
Autonomous MCP agent for grad school applications: prof discovery, cold emails, SOP, tracking.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- i-ninte
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.5
- Stars
- 4
- Forks
- 1
- Last push
- 2026-07-14T11:53:10Z
- Repository state
- ativo
- Language
- Python
- Added
- 2026-08-29 04:00:08
- Updated
- 2026-08-29 04:00:08
- Origin id
io.github.i-ninte/grad-agent
README
# grad-agent
<!-- mcp-name: io.github.i-ninte/grad-agent -->
An autonomous MCP agent that helps you apply to fully funded MS and PhD programs.
**Discover and draft**
- Discovers professors on arXiv in your research areas, or deadline-driven per program (`run_program_batch`)
- Resolves each professor's identity by anchoring on the trigger paper's canonical Semantic Scholar authorId, not the name string — name collisions like "Wei Zhang" are structurally impossible to confuse
- Refuses to draft when identity cannot be anchored; the specific mismatch (e.g. `identity ambiguous: 2 comparable candidates, h=40 vs h=38`) is persisted to a `skipped` sheet for audit
- Verifies each candidate is actually faculty (h-index and paper-count gates)
- Filters by region (`target_regions: [US, Canada]` in your profile; keyword table + homepage TLD + LLM fallback)
- Scrapes their lab page for a recruiting signal + email address
- Matches them to your strongest shipped project (tag overlap + TF-IDF semantic layer + learned response-rate bias)
- Drafts a specific, fact-checked cold email: Claude Haiku writes a hook spanning the prof's recent papers, then a second call verifies every claim against the abstracts and rewrites anything unsupported
- Scores each draft 1 to 10 for fit, with a one-line reason, so you can triage in seconds
- **Freshness warnings** on every draft: cross-checks the S2 affiliation against the prof's live homepage (flags `MISMATCH` if they may have moved labs) and flags researchers who have not published in 2+ years
**Learn and follow through**
- Detects professor replies via read-only IMAP and tags the log automatically
- Learns from outcomes: projects that earn replies rank up in future matching (`outcome_report` shows what works)
- Drafts follow-up nudges for profs silent 10+ days; never nudges the same prof twice
- Generates an interview prep one-pager when a prof replies: their papers summarised, likely questions, your talking points
**Track everything**
- Compiles per-school SOPs to PDF (LaTeX), versioned so no draft is ever overwritten
- Tracks outreach, LOR requests, program deadlines, and external scholarships (Mastercard, Commonwealth, Fulbright, Rhodes, and more) in xlsx/yaml
- Emails every draft to your inbox for review; nothing is ever sent to a professor without you
Runs as a stdio MCP server for Claude Code / Claude Desktop / any MCP client, or as a plain CLI.
Published on:
- **PyPI**: [`grad-agent`](https://pypi.org/project/grad-agent/)
- **MCP Registry**: [`io.github.i-ninte/grad-agent`](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.i-ninte/grad-agent)
## Install
Pick one:
```bash
# Recommended for MCP clients (Claude Desktop, Claude Code, etc.)
uvx grad-agent server # single-shot, no persistent install
# Persistent CLI install
pipx install grad-agent
# Or in a venv
python3 -m venv .venv && source .venv/bin/activate
pip install grad-agent
```
## Set up in 5 minutes
```bash
grad-agent init
```
This writes:
- `~/.grad-agent/profile.yaml` — your identity, projects, preferences
- `~/.grad-agent/programs.yaml` — target programs (seeded)
- `~/.grad-agent/scholarships.yaml` — external scholarships with deadlines (seeded)
- `~/.grad-agent/.env` — secrets template
Fill in `~/.grad-agent/.env`:
```
ANTHROPIC_API_KEY=sk-ant-...
SMTP_SERVER=smtp.gmail.com # presets for Outlook/Yahoo/Zoho in the template
SMTP_PORT=587
SMTP_USERNAME=you@gmail.com
SMTP_PASSWORD=<gmail app password>
SMTP_FROM=you@gmail.com
# Optional:
S2_API_KEY= # free Semantic Scholar key, dedicated rate limits
# (client-side throttle already enforces >=1.1s between requests)
IMAP_SERVER=imap.gmail.com # read-only reply detection; defaults to SMTP creds
GITHUB_USERNAME=your-gh
GITHUB_TOKEN=github_pat_...
HF_USERNAME=your-hf
```
Fill in the important bits of `~/.grad-agent/profile.yaml`:
- `name`, `identity_line`, `portfolio`
- `cv_path`, `transcript_path` (absolute paths)
- `degree_status: bachelors | masters` (drives PhD eligibility gating)
- `target_term`, `target_degree`
- `research_areas: [nlp, ai4health, ...]`
- `target_regions: [US, Canada]` — only draft for profs in these regions (empty = anywhere)
- `seed_projects:` 3 to 10 flagship projects with `name`, `pitch`, `link`, `tags`
Profile edits apply immediately, even while a long-running MCP session is open.
Then:
```bash
grad-agent sync # scan projects (GitHub + HF + local)
grad-agent run # one batch, drafts land in your inbox
```
## Register with Claude Code
Three commands, in order:
```bash
pipx install grad-agent
pipx ensurepath # macOS/Linux: opens ~/.local/bin on PATH
# Windows: opens %USERPROFILE%\.local\bin on PATH
claude mcp add grad-agent grad-agent server
```
On Windows you may need to open a new PowerShell or Terminal window after
`pipx ensurepath` for the PATH change to take effect.
Prefer a zero-install one-liner? Skip `pipx` and use `uvx`:
```bash
claude mcp add grad-agent uvx grad-agent server
```
Then in a **new** Claude Code session:
```
/mcp
```
You should see `grad-agent` connected with ~36 tools. Before it does anything useful, run `grad-agent init` (or `uvx grad-agent init`) and fill in `~/.grad-agent/.env` and `~/.grad-agent/profile.yaml` as described in the setup section above.
If you skipped `pipx ensurepath`, `grad-agent register-claude` prints an absolute-path variant of the command that works without PATH changes.
## Register with Claude Desktop
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"grad-agent": {
"command": "uvx",
"args": ["grad-agent", "server"]
}
}
}
```
The `uvx` command needs no prior install. If you already ran `pipx install grad-agent`,
you can use `"command": "grad-agent", "args": ["server"]` instead.
Any other MCP client (Cursor, Zed, Windsurf) uses the same manifest shape; just
point them at `uvx grad-agent server`.
## Daily autonomous run
The package ships scheduler templates for all three OSes. `grad-agent schedule`
emits the right one for your platform:
```bash
grad-agent schedule --dest .
```
Then follow the install instructions the command prints. In case you want them
up front:
**macOS (launchd):**
```bash
cp com.gradagent.daily.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.gradagent.daily.plist
```
**Linux (systemd user timer, fires at 08:00 local):**
```bash
mkdir -p ~/.config/systemd/user
cp grad-agent-daily.service grad-agent-daily.timer ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now grad-agent-daily.timer
```
**Windows (Task Scheduler):**
```powershell
# In an elevated PowerShell prompt:
schtasks /Create /TN "grad-agent-daily" /XML .\grad-agent-daily.xml
```
Or import the XML via the Task Scheduler GUI (Action → Import Task).
Every morning: replies auto-detected via IMAP, follow-up nudges drafted for silent profs, 3 identity-verified faculty leads with fit scores (best fit first), hooks fact-checked against paper abstracts, freshness warnings when a prof's S2 record and live homepage disagree, plus program and scholarship deadline warnings — all in one review email. Skipped leads are persisted with the specific mismatch reason (view with `skipped_log_view` or open the `skipped` sheet).
## What each MCP tool does
| Tool | Purpose |
|---|---|
| `run_daily_batch(n, area)` | Full pipeline: verify → recruiting → hook + verify → draft → log |
| `outreach_log_view(limit)` | Show last N rows of the outreach xlsx |
| `outreach_mark_sent(prof, uni)` | Flag a row as actually sent to the prof |
| `sync_catalog(source)` | Pull projects from `github`, `hf`, or `local` |
| `list_projects_in_catalog()` | Show every project the matcher can see |
| `list_programs()` | Your target programs |
| `upcoming_deadlines(days)` | Any program deadline in the next N days |
| `lor_add / lor_outstanding / lor_mark` | Recommendation-letter tracker |
| `run_program_batch(program_id, n)` | Deadline-driven batch: draft for one program's faculty |
| `skipped_log_view(limit)` | Audit trail of skipped leads with the specific stage + mismatch reason |
| `s2_cache_invalidate(query, all)` | Selectively purge Semantic Scholar cache entries by author name or id |
| `followups_due(days)` | Drafted nudges for profs silent 10+ days |
| `outreach_mark_followup(prof)` | Record a sent nudge (never nudged twice) |
| `outreach_mark_response(prof, outcome)` | Tag replies; feeds the matcher's learning loop |
| `outcome_report()` | Response rates by area and project |
| `ingest_replies()` | Read-only IMAP scan; auto-tags replies in the log |
| `interview_prep(prof)` | One-page brief: their papers, likely questions, your talking points |
| `list_scholarships(region)` | External scholarships filtered by eligibility region |
| `upcoming_scholarship_deadlines(days)` | Scholarship deadlines approaching |
| `draft_cold_email(...)` | Manual per-prof draft |
| `draft_sop(...)` | Compile a Columbia-style SOP PDF (versioned: sop_v1, v2, ...) |
| `send_draft_to_me(path)` | Ship any draft file to your review inbox |
| `discover_profs(area)` | arXiv + OpenReview scan (raw candidates, no verification) |
Blog publishing tools (`publish_article`, `update_article`, ...) are gated behind `blog.enabled: true` in `profile.yaml` and are specific to the author's Turso-backed Next.js portfolio. Most users can ignore them.
## What the agent will not do
- Send any email to a professor. Every send is manual, from your Gmail, after you read the draft.
- Touch your inbox beyond reading. IMAP access is read-only: it never sends, deletes, or marks messages.
- Fabricate a paper claim. The hook goes through a second Claude call that rejects any claim not present in the abstracts, and rewrites.
- Email the same professor twice. Deduplication is keyed on the Semantic Scholar authorId, with a name fallback for legacy rows, and follow-ups are marked so no prof is nudged more than once.
- Draft for the wrong person when two profs share a name. Identity is resolved from the trigger paper's authorId, not the name string; ambiguous cases are refused and logged.
- Hide why a lead was rejected. Every skip is persisted to the `skipped` sheet in `outreach_log.xlsx` with the stage (identity, faculty-gate, region, dedup, no-papers) and the exact mismatch — not buried in old review emails.
- Exceed Semantic Scholar's rate limit. Client-side throttle enforces ≥1.1s between requests, with exponential backoff on any 429 or 5xx.
- Draft for programs you are ineligible for. If your `degree_status` is `bachelors`, PhD programs that require an MSc first are filtered out. Same gate for scholarships outside your eligibility region.
## Requirements
- Python 3.10+
- macOS, Linux, or Windows (all three tested in CI on 3.10 / 3.11 / 3.12)
- `pdflatex` on PATH if you want SOP PDFs
(macOS: MacTeX; Ubuntu: `texlive-latex-recommended`; Windows: MiKTeX)
- Anthropic API key
- Gmail (or another SMTP) for the review-mailer
## Where your data lives
Everything is under `~/.grad-agent/` by default, or `$GRAD_AGENT_HOME` if set:
```
~/.grad-agent/
profile.yaml identity + preferences (regions, seed projects, ...)
programs.yaml target programs with eligibility rules + deadlines
scholarships.yaml external scholarships with region eligibility + deadlines
.env secrets (gitignored)
data/
outreach_log.xlsx outreach sheet (drafts + outcomes) + skipped sheet (audit trail)
lor_log.xlsx recommendation-letter tracker
catalog.json synced projects (GitHub + HF + local)
s2_cache.json Semantic Scholar lookups (14 day TTL)
region_cache.json LLM-inferred regions for unusual affiliations
db.sqlite drafts + status
drafts/ per-school SOP versions + email drafts
prep/ interview prep one-pagers
```
## Contributing
MIT licensed. PRs welcome for: more program templates, non-Gmail SMTP presets, non-arXiv source adapters, and better prof-verification heuristics.
## Author
Kwabena Obeng · [i-ninte.github.io/portfolio/](https://i-ninte.github.io/portfolio/)