
grad-agent
io.github.i-ninte由 GitHub 账号 i-ninte 发布v0.2.9更新于 Oct 24, 2026
Autonomous MCP agent for grad school applications: prof discovery, cold emails, SOP, tracking.
概览
面向研究生申请的本地 MCP 智能体:发现教授、起草经事实核查的冷邮件、SOP 与推荐信,并跟踪联系进度和截止日期。
- 可以做什么
- 发现并核实教授:扫描 arXiv 与 OpenReview,解析身份,按教职资格和地区筛选,抓取实验室主页的招生信号与邮箱,跳过的线索会记录原因。起草联系邮件:围绕教授近期论文撰写冷邮件,对照摘要核查论断,给出匹配评分,并把草稿发到你的收件箱供审阅。跟踪联系:查看和更新联系记录,标记已发送、回复与跟进,并按领域和项目统计回复率。处理申请材料:编译带版本号的 SOP PDF,跟踪推荐信、项目、截止日期和奖学金,生成面试准备简报。从 GitHub、HuggingFace 和本地同步项目目录。
- 适用场景
- 适合正在申请有资助的硕士或博士项目、希望协助寻找和甄别导师、起草个性化联系邮件与 SOP,并把截止日期、推荐信和回复集中跟踪的人。它不是通用的邮件或科研工具。
- 运行要求
- 本地 Python 3.10+ 进程,通过 uvx 或 pipx 在 macOS、Linux 或 Windows 上运行。必需:ANTHROPIC_API_KEY 以及 SMTP 配置(SMTP_SERVER、SMTP_PORT、SMTP_USERNAME、SMTP_PASSWORD、SMTP_FROM)。可选:GITHUB_TOKEN、HF_TOKEN、IMAP 配置、S2_API_KEY、GRAD_AGENT_HOME、LOR_LETTERHEAD_PATH。生成 SOP PDF 需要 pdflatex;需能访问 arXiv、Semantic Scholar、GitHub 和 HuggingFace。
安装
在 SourceWeft 中
- 打开 控制台中的 grad-agent,将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。
其他 MCP 客户端
参照 仓库 中的启动说明。
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/
来源:README.md,提交 0e45d9b
工具
0版本历史
2- v0.2.9最新Sep 25, 2026
- v0.2.5Sep 16, 2026
评分
已满足适用检查项的 40%
该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。
- 近 30 天内可连通25 分
请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。
- 已声明认证方式10 分
请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分
请在仓库或注册中心条目中声明许可证。