
grad-agent
io.github.i-nintePublished by GitHub account i-nintev0.2.9Updated Oct 24, 2026
Autonomous MCP agent for grad school applications: prof discovery, cold emails, SOP, tracking.
Overview
A local MCP agent for graduate school applications that finds professors, drafts fact-checked cold emails, SOPs and LORs, and tracks outreach and deadlines.
- What you can do
- Discover and verify professors: scan arXiv and OpenReview, resolve identities, gate on faculty status and region, and scrape lab pages for recruiting signals and emails, with skipped leads logged and explained. Draft outreach: write cold emails anchored to recent papers, fact-check claims against abstracts, score fit, and email drafts to your own inbox for review. Track outreach: view and update the outreach log, mark sends, responses and follow-ups, and report response rates by area and project. Handle applications: compile versioned SOP PDFs, track recommendation letters, programs, deadlines and scholarships, and generate interview prep briefs. Sync a project catalog from GitHub, HuggingFf
- When to use it
- Use it if you are applying to funded MS or PhD programs and want help finding and vetting faculty, drafting personalized outreach and SOPs, and keeping deadlines, letters and replies in one tracked workflow. It is not a general email or research tool.
- Requirements
- Local Python 3.10+ process, run via uvx or pipx on macOS, Linux or Windows. Required: ANTHROPIC_API_KEY and SMTP settings (SMTP_SERVER, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, SMTP_FROM). Optional: GITHUB_TOKEN, HF_TOKEN, IMAP settings, S2_API_KEY, GRAD_AGENT_HOME, LOR_LETTERHEAD_PATH. pdflatex needed for SOP PDFs; network access to arXiv, Semantic Scholar, GitHub and HuggingFace.
Installation
In SourceWeft
- Open grad-agent in the dashboard and add it to a workspace.
- Enable the server for the chats that should use its tools.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Other MCP clients
Follow the launch instructions in the repository.
README
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:
Set up in 5 minutes
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:
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:
Register with Claude Code
Three commands, in order:
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:
Then in a new Claude Code session:
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:
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:
Then follow the install instructions the command prints. In case you want them up front:
macOS (launchd):
Linux (systemd user timer, fires at 08:00 local):
Windows (Task Scheduler):
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
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:
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/
Source: README.md at commit 0e45d9b
Tools
0Version history
2- v0.2.9LatestSep 25, 2026
- v0.2.5Sep 16, 2026
Score
40% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
- Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
- Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
- Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
- DescriptionRequired15 pts
- Logo10 pts
- Documentation15 pts
- License10 pts
Declare a license in the repository or the registry entry.