Job Outreach MCP
README.md
# Job Outreach MCP (Phase 1)
Duplicate-safe recruiter / HR cold-email assistant for Claude.
**What it does:** finds contacts -> removes duplicates -> Claude writes emails -> Gmail drafts -> you approve ->
send (capped per day) -> follow-ups -> reply/bounce tracking -> stats.
## Duplicate protection (enforced in code, not by Claude)
- Emails normalised (lowercase, `+tag` removed); one row per email.
- Same person (first+last name at same company domain) cannot be listed twice, even with 2 addresses.
- Database rule `UNIQUE(contact, kind)`: one initial, one follow-up 1, one follow-up 2 per contact, ever.
- Replied / bounced / do-not-contact people are locked out. Blocklist supports emails and whole domains.
- Sent emails can never be sent again.
## Setup
1. Requirements: Node.js 20.12+.
2. `npm install && npm run build`
3. Google Cloud Console: create a project -> enable **Gmail API** -> OAuth consent screen (add yourself as a test user)
-> Credentials -> **OAuth client ID, type "Desktop app"**. Copy `.env.example` to `.env`, fill client id/secret.
Add `http://localhost:3000/oauth2callback` as an authorised redirect URI if asked.
4. `npm run auth` -> open the printed link -> approve. Token is saved in `data/token.json`.
5. (Optional) Add `HUNTER_API_KEY` to `.env` for automatic contact finding. Without it, use `add_contact`.
6. Sending is OFF by default (`ALLOW_SEND=false`): drafts are created, nothing is sent. Turn on after testing.
## Connect to Claude
Claude Desktop -> Settings -> Developer -> Edit config:
```json
{
"mcpServers": {
"job-outreach": {
"command": "node",
"args": ["/ABSOLUTE/PATH/job-outreach-mcp/dist/index.js"]
}
}
}
```
Restart Claude Desktop. (Claude Code: `claude mcp add job-outreach -- node /ABSOLUTE/PATH/dist/index.js`.)
## Add the skill
Edit your profile in `skill/SKILL.md`, zip the `skill` folder (rename folder to `job-outreach`), and upload it under
Settings -> Capabilities -> Skills.
## Try it
> "Find 10 HR contacts at infosys.com and write drafts for a Business Analyst role in Pune."
## Roadmap
Resume attachment, job-suggestion agent (LangGraph), weekly report agent, referral finder, A/B subject lines.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues