# MCP Email Server (Gmail)

An MCP server that lets Claude send emails from your Gmail account — with attachments
(e.g. your resume) — and pull your profile/resume summary for tailoring outreach.

Tools exposed to Claude:
- `send_email` — sends an email, optional attachment from `attachments/`
- `list_attachments` — lists files available to attach
- `get_profile` — returns your `profile.md` (skills, education, experience)

---

## 1. Google Cloud setup (one-time)

1. Go to [console.cloud.google.com](https://console.cloud.google.com/) and create a new project
   (or use an existing one).
2. Go to **APIs & Services > Library**, search for **Gmail API**, and click **Enable**.
3. Go to **APIs & Services > OAuth consent screen**.
   - User type: **External** (unless you have a Workspace account).
   - Fill in app name, your email as support/contact.
   - Add your own Gmail address under **Test users** (required while the app is unpublished).
4. Go to **APIs & Services > Credentials > Create Credentials > OAuth client ID**.
   - Application type: **Desktop app**.
   - Save the **Client ID** and **Client Secret**.

## 2. Local setup

```bash
cd mcp-email-server
npm install
cp .env.example .env
```

Edit `.env` and paste in your `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`.

## 3. Authorize (one-time)

```bash
npm run authorize
```

This opens a URL — open it in your browser, sign in with the Gmail account you want to
send from, and approve access. The script will print a `GOOGLE_REFRESH_TOKEN` — paste
that into your `.env` file too.

## 4. Add your resume and profile

- Drop your resume PDF into `attachments/` (e.g. `attachments/resume.pdf`)
- Fill in `profile.md` with your skills, education, and experience — Claude will read
  this via `get_profile` to tailor cover letters to each job posting.

## 5. Connect to Claude

There are two server modes, depending on which Claude client you want to use.

### Option A — Claude Desktop / Claude Code (local, simplest)

Uses `src/index.js` (stdio transport) — runs on your machine, no deployment needed.

Edit your MCP config (`claude_desktop_config.json` or equivalent) and add:

```json
{
  "mcpServers": {
    "email-outreach": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-email-server/src/index.js"]
    }
  }
}
```

Restart Claude Desktop. The tools (`send_email`, `list_attachments`, `get_profile`)
will then be available in chat.

### Option B — Claude web / mobile / Desktop via Custom Connector (remote)

Claude web and mobile can **only** use remote MCP servers — reachable over the public
internet from Anthropic's cloud, not a process running on your laptop. Use
`src/http-server.js` for this.

**1. Set an auth token.** Since this server will be reachable by anyone with the URL,
generate a secret and put it in `.env`:

```bash
openssl rand -hex 32
```

Paste the result into `.env` as `MCP_AUTH_TOKEN=...`.

**2. Deploy it somewhere public with HTTPS.** Any Node-friendly host works —
Railway, Render, Fly.io, a VPS, etc. The important parts:
- Set the same environment variables from your `.env` (`GOOGLE_CLIENT_ID`,
  `GOOGLE_CLIENT_SECRET`, `GOOGLE_REFRESH_TOKEN`, `MCP_AUTH_TOKEN`) on the host.
- Upload `profile.md` and `attachments/resume.pdf` to the host too (or bake them
  into the deploy) — they're read from disk at runtime.
- Start command: `npm run start:http`
- The server listens on `process.env.PORT` (most hosts set this automatically)
  and exposes the MCP endpoint at `/mcp`.

**3. Add it to Claude as a custom connector:**
- Go to **Settings → Connectors → Add custom connector** (in claude.ai, Cowork,
  or Desktop — they all use the same account-level connector list)
- If your dialog shows an Advanced settings → **Request headers** section: add
  `Authorization: Bearer <your MCP_AUTH_TOKEN>` there, and use the plain URL
  (`https://your-deployed-domain.com/mcp`).
- If it doesn't (this is a beta feature Anthropic is still rolling out — some
  accounts only see Name / URL / OAuth Client ID / OAuth Client Secret): put
  the token in the URL as a query param instead:
  `https://your-deployed-domain.com/mcp?token=<your MCP_AUTH_TOKEN>`
  The server accepts the token either way. Query-param tokens are logged more
  easily than headers, so treat the URL itself as a secret — don't paste it
  anywhere public.
- Save, then enable it in your conversation via the "+" → Connectors menu

Once added, `send_email`, `list_attachments`, and `get_profile` are available from
any device — web, mobile, or desktop — all connecting to the same account.

**Security note:** this endpoint can send email from your Gmail account, so treat
`MCP_AUTH_TOKEN` like a password. Don't commit it, don't share the URL+token
publicly, and rotate it if you suspect it leaked.

## 6. Usage examples

- *"Send an email to jane@company.com letting her know I'll be 10 minutes late to our call."*
- *"Here's a job posting: [url]. Read it, check it against my profile, and draft a
  tailored email + cover letter to hr@company.com with my resume attached. Show me
  the draft before sending."*
- *"Here are 10 HR emails: [list]. For each, I'll give you the job posting link —
  personalize the email to that role and send with my resume attached."*

## Notes on safe/effective use

- **Gmail sending limits**: personal Gmail accounts are capped around 500 emails/day
  (2,000/day for Workspace) — irrelevant at 10 emails, but worth knowing if you scale up.
- **Personalize each email.** Cold outreach that's obviously templated performs worse
  and can get flagged as spam. Have Claude pull 2-3 specific details from each job
  posting/company rather than doing pure find-and-replace.
- **Always review before sending.** Claude will draft the email and should show it to
  you before calling `send_email` — treat this as a hard rule when you set up your
  instructions to Claude.
- **Scope of the OAuth token**: this app only requests `gmail.send` — it cannot read
  your inbox or delete anything.
- Keep `.env` and anything in `attachments/` out of version control (already handled
  by `.gitignore`).