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 askippedsheet 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
MISMATCHif 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_reportshows 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
Bundled Claude Code / Claude Desktop skills
Installing grad-agent ships a set of Anthropic Skills you can invoke from any Claude client that supports them (Claude Code, Claude Desktop, MCP-aware IDEs). grad-agent init symlinks them into ~/.claude/skills/ automatically; to (re)install without running init, use grad-agent install-skills (add --force to replace existing entries, or --target <dir> to link elsewhere).
sop-writing— rules for MS/PhD Statement of Purpose drafting, synthesized from MIT CommLab, MIT CAPD, Berkeley Grad Div, Harvard GSAS, Stanford, and CS-faculty guides. Pairs with the LaTeX SOP compile step.lor-writing— rules for letters of recommendation, including the common case where the applicant ghost-drafts a letter for a recommender to sign. Encodes multi-letter differentiation, recommender realism, HHMI bias hygiene, and a banned-phrase regex sweep. Supports an optional letterhead / company logo via theLOR_LETTERHEAD_PATHenv var (withLOR_LETTERHEAD_WIDTH, default2.2in) so the LaTeX compile drops your image into the top of the letter — leave it unset for a plain top block the recommender can paste onto their own letterhead.grad-agent initwill prompt for the letterhead path interactively; to change it later (or swap letterheads between recommenders) rungrad-agent set-letterhead /path/to/image.png --width 2.5in(pass no path to clear it).- Cold-email drafter (
grad_agent/drafters/cold_email.py) — rewritten around PhD outreach best-practices (specific paper anchor, one concrete overlap, no un-anchored superlatives, no "I read your paper" claims).
Runs as a stdio MCP server for Claude Code / Claude Desktop / any MCP client, or as a plain CLI.
Published on:
- PyPI:
grad-agent - MCP Registry:
io.github.i-ninte/grad-agent
Install
Pick one:
# 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
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,portfoliocv_path,transcript_path(absolute paths)degree_status: bachelors | masters(drives PhD eligibility gating)target_term,target_degreeresearch_areas: [nlp, ai4health, ...]target_regions: [US, Canada]— only draft for profs in these regions (empty = anywhere)seed_projects:3 to 10 flagship projects withname,pitch,link,tags
Profile edits apply immediately, even while a long-running MCP session is open.
Then:
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:
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:
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:
{
"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:
grad-agent schedule --dest .
Then follow the install instructions the command prints. In case you want them up front:
macOS (launchd):
cp com.gradagent.daily.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.gradagent.daily.plist
Linux (systemd user timer, fires at 08:00 local):
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):
# 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
skippedsheet inoutreach_log.xlsxwith 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_statusisbachelors, 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)
pdflatexon 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/
Metadata
Release files for grad-agent 0.2.9
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| grad_agent-0.2.9.tar.gz | 77.5 kB | Without provenance | Details for grad_agent-0.2.9.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| grad_agent-0.2.9-py3-none-any.whl | Python 3 | none | any | Details for grad_agent-0.2.9-py3-none-any.whl |
Total release size: 169.2 kB
Release files / grad_agent-0.2.9.tar.gz
| Download URL | grad_agent-0.2.9.tar.gz |
|---|---|
| Size | 77.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ba8dc09d300798206998c92026c4b5bfab64aa4c407c34222bbf26000bdbdf84
|
|
BLAKE2b-256 checksum How to use checksums |
8f0bfd48e6e57bc35a518dae11d86906226ca08fed85405da90ff71acf548f59
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.2
|
Release files / grad_agent-0.2.9-py3-none-any.whl
| Download URL | grad_agent-0.2.9-py3-none-any.whl |
|---|---|
| Size | 91.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
aca5a0c08bf4aca02fefb0c0765bb50a4a0540f36f382884e8e1eb7a7a4d4e44
|
|
BLAKE2b-256 checksum How to use checksums |
ea5e7129d40d4d7dbf4d13e7cf05d042aa2fd63fafdd9a3cc628465a5670463c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.2
|
Security for grad-agent 0.2.9
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.