
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 分
請在儲存庫或註冊中心條目中宣告授權條款。