# RecruitMCP **Repository Path**: lookyourdad/recruit-mcp ## Basic Information - **Project Name**: RecruitMCP - **Description**: RecruitMCP 是一款开源的 MCP Server 项目,专为 Claude Desktop / Cursor 等 AI 客户端设计,实现 HR 招聘全流程自动化。 • 智能简历解析(PDF/Word,中英文) • AI 简历 vs JD 匹配打分 • 自动生成面试题、候选人画像、Offer Letter • 一键创建 Google 日历面试 • 招聘进度报表(Excel + PDF) - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-04-17 - **Last Updated**: 2026-05-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # RecruitMCP RecruitMCP 是一个面向招聘场景的 MCP Server,目标是让 Claude / Cursor / Windsurf 等支持 MCP 的客户端,通过自然语言完成招聘流程中的核心动作: - 简历解析 - JD 智能筛选 - 候选人入库与流程状态管理 - 面试日程与招聘邮件联动 - 招聘报表导出 - 候选人画像、面试问题、Offer 草拟、招聘邮件文案、简历差距分析 项目技术栈: - Python 3.11+ - `mcp[cli]` + FastMCP - SQLite + SQLAlchemy - PyMuPDF / pdfplumber / python-docx - Google Calendar API + Gmail API(OAuth2) - pandas + openpyxl + reportlab - Jinja2 - asyncio + httpx ## 项目结构 ```text RecruitMCP/ ├── main.py ├── tools/ │ ├── __init__.py │ ├── resume_parser.py │ ├── screening.py │ ├── candidate_db.py │ ├── calendar_email.py │ ├── reports.py │ └── generators.py ├── models/ │ ├── __init__.py │ └── candidate.py ├── database.py ├── config.py ├── utils/ │ ├── __init__.py │ └── helpers.py ├── data/ │ ├── email_templates/ │ ├── resumes/ │ ├── generated/ │ └── logs/ ├── migrations/ ├── .env.example ├── Dockerfile ├── pyproject.toml ├── README.md └── requirements.txt ``` ## 已实现 MCP Tools - `parse_resume` - `screen_candidate` - `save_candidate` - `list_candidates` - `update_candidate_status` - `schedule_interview` - `send_email` - `generate_report` - `generate_interview_questions` - `generate_candidate_summary` - `draft_offer_letter` - `generate_recruitment_email` - `analyze_resume_gaps` ## 环境准备 ### 1. 安装依赖 ```bash python -m venv .venv . .venv/Scripts/activate pip install -r requirements.txt ``` 如果需要解析旧版 `.doc`,请确保系统中安装了 `antiword` 并加入 PATH。 ### 2. 配置环境变量 复制 `.env.example` 为 `.env`,并根据实际情况填写: ```env APP_NAME=RecruitMCP ENVIRONMENT=development LOG_LEVEL=INFO TIMEZONE=Asia/Shanghai DATABASE_URL=sqlite+aiosqlite:///./data/recruitmcp.db DEFAULT_TRANSPORT=stdio SSE_HOST=0.0.0.0 SSE_PORT=8000 SSE_PATH=/sse ENABLE_SAMPLING_GENERATION=true REQUIRE_CONFIRMATION_BY_DEFAULT=true MAX_REPORT_ROWS=5000 GOOGLE_CREDENTIALS_FILE=./data/oauth/credentials.json GOOGLE_TOKEN_FILE=./data/oauth/token.json GOOGLE_CALENDAR_ID=primary GMAIL_SENDER= ANTHROPIC_API_KEY= ANTHROPIC_BASE_URL=https://api.anthropic.com ANTHROPIC_MODEL=claude-sonnet-4-20250514 ``` ### 3. Google OAuth 凭证 将 Google OAuth Client Secret JSON 放到: ```text ./data/oauth/credentials.json ``` 首次调用 `send_email` 或 `schedule_interview` 时,会自动触发本地 OAuth 授权流程,并将 token 写到: ```text ./data/oauth/token.json ``` ## 本地运行 ### stdio 模式 ```bash python main.py --transport stdio ``` ### SSE 模式 ```bash python main.py --transport sse --host 0.0.0.0 --port 8000 ``` SSE 服务启动后,可使用: - SSE endpoint: `http://127.0.0.1:8000/sse` - message endpoint: `http://127.0.0.1:8000/messages/` ## MCP Inspector 调试 官方 Python SDK 推荐使用 `mcp dev` 启动 Inspector: ```bash uv run mcp dev main.py ``` 如果项目还没装到当前环境,也可以: ```bash uv run mcp dev main.py --with-editable . ``` ## Claude Desktop 连接方式 推荐使用官方安装命令: ```bash uv run mcp install main.py --name "RecruitMCP" -f .env ``` 也可以手动在 Claude Desktop 的 MCP 配置中添加 stdio server,等价命令如下: ```json { "mcpServers": { "RecruitMCP": { "command": "python", "args": ["E:/code_repo/RecruitMCP/main.py", "--transport", "stdio"], "cwd": "E:/code_repo/RecruitMCP" } } } ``` ## 安全设计 - 所有写操作默认支持人工确认: - `save_candidate` - `update_candidate_status` - `send_email` - `schedule_interview` - `draft_offer_letter(save_to_file=true)` - 文件读取与写入限制在 `./data/` 目录内 - 所有 MCP tool 调用都会记录日志到 `./data/logs/recruitmcp.log` - 所有生成工具支持: - 本地规则/模板兜底 - MCP sampling 增强(当客户端支持时) ## 典型调用流程 ### 1. 解析简历 ```json { "file_path": "resumes/sample_resume.pdf" } ``` ### 2. 筛选匹配 ```json { "resume_json": {}, "jd_text": "我们需要一位 5 年以上 Python 后端工程师,熟悉 FastAPI、SQL、Docker、AWS ..." } ``` ### 3. 保存候选人 ```json { "candidate_data": {}, "require_confirmation": true } ``` ### 4. 生成候选人画像 ```json { "resume_json": {} } ``` ### 5. 生成针对性面试问题 ```json { "resume_json": {}, "jd_text": "...", "num_questions": 8 } ``` ### 6. 生成 Offer 草稿 ```json { "candidate_id": 1, "offer_details": { "company_name": "示例科技", "position_title": "高级后端工程师", "start_date": "2026-05-06", "base_salary": "40K x 14" } } ``` ## Docker 构建镜像: ```bash docker build -t recruitmcp . ``` 以 SSE 模式运行: ```bash docker run --rm -p 8000:8000 recruitmcp python main.py --transport sse --host 0.0.0.0 --port 8000 ``` ## 实现说明 - 生成类工具优先使用本地模板/规则保证稳定性。 - 如果连接的 MCP 客户端支持 sampling,这些工具会自动请求模型协助润色输出。 - 如果客户端不支持 sampling,但配置了 `ANTHROPIC_API_KEY`,生成类工具会自动回退到 Anthropic Messages API。 - `send_email` 和 `schedule_interview` 在 Google API 不可用时会自动退化为本地预览文件,方便开发联调。