# techtv-mail — a Cowork connector for pete@techtv.live

This is a small MCP server that lets Claude (Cowork) read and send email
through your cPanel-hosted `pete@techtv.live` mailbox — the same way it
already works with your Microsoft 365 and Gmail accounts, just built
specifically for this mailbox since Anthropic doesn't have a pre-built
connector for generic IMAP/cPanel mail.

It exposes four tools to Claude:

- `list_folders` — see what mail folders exist
- `search_emails` — search a folder by sender, subject, body text, or recency
- `get_email` — fetch the full text/html of one message
- `send_email` — send mail **as pete@techtv.live**

## 1. Deploy it somewhere that's always on

This needs to live on a small server that's reachable over the public
internet 24/7 — it can't live on your own computer or in a Claude session,
since both go offline. The cheapest, simplest options for something this
small:

- **Railway** (railway.app) — free/cheap tier, deploys straight from a zip
  or a GitHub repo, sets `PORT` for you automatically.
- **Render** (render.com) — similar, has a free tier for small services
  (may sleep when idle on the free tier, which adds a few seconds' delay
  on the first request after a while).
- A small VPS you already have, if you'd rather run it yourself.

Whichever you pick, the steps are the same shape:

1. Upload this folder (or push it to a GitHub repo and connect that repo).
2. Set it to run `npm install` then `npm start` (or `node server.js`).
3. Set the environment variables below in that host's dashboard —
   **never put real credentials in the code or commit them to git.**
4. Once deployed, the host gives you a public URL, e.g.
   `https://techtv-mail-production.up.railway.app`.

## 2. Environment variables to set on the host

| Variable       | Value                                    |
|----------------|-------------------------------------------|
| `MAIL_HOST`    | `mail.techtv.live`                        |
| `IMAP_PORT`    | `993`                                     |
| `SMTP_PORT`    | `465`                                     |
| `EMAIL_USER`   | `pete@techtv.live`                        |
| `EMAIL_PASS`   | the mailbox's real password                |
| `ACCESS_TOKEN` | a long random string — see below           |

To generate a good `ACCESS_TOKEN`, run this on any machine with Node or
just use a password generator for something like 40+ random characters:

```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

This token becomes part of the server's URL and is the only thing standing
between the public internet and your mailbox, so treat it exactly like a
password — long, random, never shared, never posted anywhere public.

## 3. Add it to Cowork as a custom connector

Once deployed, in the Claude app:

1. Go to **Customize > Connectors** (or click "+" / type "/" in a chat and
   choose "Manage connectors").
2. Click **+** to browse, then **Add custom connector**.
3. For the server URL, enter:

   ```
   https://<your-host-domain>/mcp/<ACCESS_TOKEN>
   ```

   (both pieces come from your deployment — the domain your host gave you,
   and the token you set as an environment variable).
4. Leave the OAuth Client ID/Secret fields blank — this server doesn't use
   OAuth, the token in the URL is the access control.
5. Save/Connect. Claude should now list `list_folders`, `search_emails`,
   `get_email`, and `send_email` as available tools whenever this connector
   is enabled in a chat.

## Security notes

- The mailbox password only ever lives in the host's environment variables
  — it's never in this code, never typed into a chat with Claude.
- Anyone who obtains the full connector URL (including the token) could
  use these tools against the mailbox, so don't paste that URL anywhere
  public (a shared doc, a public repo, a Slack channel others can see).
- If you ever suspect the URL has leaked, generate a new `ACCESS_TOKEN`,
  update it on the host, and re-enter the new URL in Cowork's connector
  settings — the old URL stops working immediately.
- This mailbox's actual password should also just live in your password
  manager as normal; this server needs it once, at deploy time, as an
  environment variable.

## Local test (optional, before deploying)

You can run it locally first to make sure your real credentials work:

```bash
npm install
MAIL_HOST=mail.techtv.live IMAP_PORT=993 SMTP_PORT=465 \
EMAIL_USER=pete@techtv.live EMAIL_PASS='<real password>' \
ACCESS_TOKEN=test123 PORT=3000 node server.js
```

Then in another terminal:

```bash
curl -s -X POST http://localhost:3000/mcp/test123 \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
```

A successful response looks like a `result` block naming the server —
if instead you get an authentication error, double check `EMAIL_PASS` and
that IMAP/SMTP access isn't blocked for this mailbox in cPanel.