# Build Your Own Mail MCP Server

A step-by-step guide for assistants who are not developers.

This is the path I took to get one AI agent working across two Gmail
inboxes, written out so you can follow it. You do not need to know how to
code. You do need to be willing to open a terminal and paste things into
it, and to be patient with the setup, which is the boring part.

---

## What you will end up with

An agent that can read, search, draft, and label mail across more than one
Gmail account at once, and that cannot send.

Not "cannot send because I told it not to." Cannot send because the
capability is not in the thing. A rule can be broken. A missing capability
cannot. That distinction is the whole reason I built my own rather than
working around the limits of something off the shelf.

## What this will not do

Be honest with yourself about this before you spend a Saturday on it.

- **It will not send mail.** By design. Drafts land in your Drafts folder
  and wait for you.
- **It will not work in the Claude web app.** A server like this runs on
  your own computer and connects through Claude Desktop only. If you work
  entirely in a browser, this specific approach is not for you.
- **It will not be finished.** Mine reads, searches, drafts, and labels.
  That is all. You add tools one at a time as you need them.

---

## Before you start

**A computer you can install things on.** A work laptop with locked-down
admin rights will fight you. Mine is a personal machine.

**Claude Desktop**, downloaded and installed. The web app will not do. See
above.

**Python**, installed. Open Terminal (Mac) or Command Prompt (Windows) and
type `python3 --version`. If you get a version number, you have it. If you
get an error, install it from python.org first.

**About two hours** for the first pass, most of it spent on Google's
permission screens rather than on anything resembling building.

**One Gmail account to start with.** Not two. The single most useful piece
of advice I got was to stop planning the whole system and build the
smallest thing that proves one connection works. Do that first. Add the
second account after the first one works.

---

## Step 1: Turn off the Gmail connector first

Do this before anything else, and do not skip it.

If the standard Gmail connector is still switched on while your own server
is running, you will have two different pieces of software reaching the
same mailbox. Both of them work. Neither of them tells you which one just
answered. You will spend an afternoon debugging your code when the problem
is that the other thing responded.

In Claude, open Settings, then Connectors, and disconnect Gmail.

Then check it actually went away rather than trusting that it did. Start a
new conversation and ask what mail tools are available. You want to see
only your own. If a vendor Gmail tool is still listed, it is still
connected somewhere. Check both the conversation-level toggles and your
account-level connector settings, because those are two different switches.

This check is worth repeating any time mail behaviour gets strange later
on. A connector re-enabling itself after an update is a real thing that
happens.

---

## Step 2: Get your own Google credentials

Your server needs its own permission to talk to Gmail. This is the part
that feels most like paperwork, and it is where most people give up. It is
genuinely tedious and it is genuinely not hard.

Go to the Google Cloud Console and, in order:

1. **Create a project.** Name it something you will recognise in a year.
2. **Enable the Gmail API** for that project. There is a library of APIs;
   find Gmail, turn it on.
3. **Configure the consent screen.** Choose External unless you are on
   Google Workspace and know otherwise. Fill in the minimum: app name, your
   email, your email again.
4. **Add yourself as a test user.** This is the step people miss. Without
   it your own account cannot authorise your own app, and the error message
   will not tell you that.
5. **Create OAuth credentials** of type Desktop app. Download the JSON file
   it gives you.

That downloaded file is a key to your mailbox. Treat it like one.

**On scopes:** you will be asked which permissions your app wants. Ask for
the narrowest set that does what you need, which is reading, drafting, and
modifying labels. Do not ask for send permission. If the ability to send is
never granted, it cannot be used by accident, and you have a much better
answer than "I trust it."

Google changes this interface regularly, so the labels above may not match
your screen exactly. The five things you need are the same regardless:
project, Gmail API on, consent screen, yourself as a test user, desktop
credentials downloaded.

---

## Step 3: Put the credentials somewhere safe

Not in the folder with your code. Outside it entirely, in a hidden config
directory that only your user account can open.

The reason is that code folders end up shared. They get zipped and emailed,
committed to version control, synced to Dropbox, handed to someone helping
you debug. Anything sitting in that folder goes with them. Credentials kept
somewhere separate simply cannot make that trip.

Mine live in a folder under my home directory, created so that only my
account can read it. Ask Claude to set this up for your operating system
and to explain what it did.

While you are there: if you use version control, add the credential
filenames to your ignore list before your first commit. Not after.

---

## Step 4: Build the smallest possible version

Here is the temptation, and I fell for it: sit down and design the whole
system. All the tools, the perfect structure, how it will handle every case.

Do not do this. I spent weeks on an architecture that turned out to rest on
two assumptions that were both wrong. I found that out on day one of
actually building, which was lucky. Three weeks in would have hurt.

**Build one tool. Make it list the subject lines in one inbox.**

That is it. If that works, everything else is variations on it: you have
proved you can authenticate, reach Gmail, get real data back, and hand it
to the agent. Every other tool you write is a change of verb.

Ask Claude to write you a minimal MCP server in Python with a single tool
that lists recent message subjects from one Gmail account, using the
credentials file you downloaded. Then ask it to explain each part. You will
understand the second version much better for having watched the first one
work.

The first time you run it, Google will open a browser window asking you to
authorise. Say yes. That exchange gets saved, so you will not be asked
every time.

---

## Step 5: Connect it to Claude Desktop

Claude Desktop needs to be told your server exists.

Open Claude Desktop's settings from the menu bar (the Claude menu at the
top of the screen, not the settings inside the chat window). Go to the
Developer tab and click Edit Config. That opens a file called
`claude_desktop_config.json`, creating it if it is not there yet.

Inside it you add an entry naming your server, the command that runs it,
and where it lives:

```json
{
  "mcpServers": {
    "my-mail": {
      "command": "python3",
      "args": ["/full/path/to/your/server.py"]
    }
  }
}
```

Use the full path, starting from the top of your drive. A shortened or
relative path is the most common reason a server silently fails to appear.

Then quit Claude Desktop completely and reopen it. Not close the window.
Quit. It only reads that file on startup.

If your server does not show up, the logs will tell you why. On a Mac they
are in `~/Library/Logs/Claude`, and the file named for your server holds
its error output. Reading that file is faster than guessing, every time.

---

## Step 6: Verify it before you trust it

This is the step that separates a thing you use from a thing you hope
about, and it is the step almost nobody writes about.

Two failure modes matter here more than ordinary bugs. The server reaching
an account you never meant to connect. And reads or writes landing in the
wrong mailbox, which in a mail context means the wrong person's
correspondence. Neither of those shows up as an error message. Both look
exactly like success.

So do not ask the tool whether it worked. Check separately.

Work through these in order, and stop at the first thing that surprises you:

1. **Ask what accounts it can reach, before reading any mail.** You should
   see exactly the accounts you connected. Not one more.
2. **Check no other mail tool is running.** Back to step 1.
3. **Read each account on its own.** Subjects only. Two different accounts
   should give you two completely different sets of mail.
4. **Search each account on its own.** A search bounded by date is easiest
   to sanity-check.
5. **Write one test draft into each account.** Then confirm it landed
   correctly with a separate command that lists drafts across every
   account. Not by reading the success message from the write itself. Each
   account should have gained exactly one draft, and nothing should have
   crossed over.
6. **Search both accounts at once** for something you know exists in both.
   Every single result should say which account it came from.
7. **If you added labels,** create one in a single account and confirm it
   did not appear in the other. Apply it, find it by searching, remove it,
   and confirm nothing was left behind.

**One thing to expect, because it looks alarming and is not:** if two of
your addresses were both on the same email thread, that message will show
up in both accounts. Same sender, same subject, same timestamp. That is not
a leak. Gmail stored a genuine separate copy in each mailbox, each with its
own ID, often sent from one account and received in the other. When I hit
this I assumed I had a serious bug. It was the system correctly reflecting
reality.

Which is the actual lesson: verify until something surprises you, then work
out whether it is a bug or proof that it is working. Tests that all pass
tell you less than you think.

---

## Step 7: Add one tool at a time

Now widen it. Reading a full message, reading a thread, searching,
drafting, editing a draft, labels. One at a time, each verified with an
independent read-back before you move on.

**Add the second account only after the first one is solid.** When you do,
make every tool take an account as an input, and make every result say
which account it came from. If a result cannot tell you where it came from,
you cannot safely act on it.

**Keep send out.** Every time. It is the constraint that makes the rest of
it safe to use.

---

## Known limitations to plan for

These are real ones from my build, and yours will have them too. Write
yours down as you find them.

**Results stop silently.** Reads and searches cap out at a fixed number of
results and do not tell you when there was more. A seven-day search handed
me three days of mail and looked complete. This is the failure mode I care
about most, because it looks exactly like success. You will confidently
tell someone there is nothing else when there is. The cheap fix is not full
pagination: Gmail already tells you when more results exist, so have your
server pass that along as a line saying more is available. Do that before
you rely on any search being complete.

**Listing shows previews.** Asking for subjects only still returns a snippet
of the body. Fine most of the time, worth knowing if you were trying to
keep contents out of the conversation.

**Labels are one-way.** You can create them but not delete them through the
server. A test label, or one with a typo in it, stays until you remove it
by hand in Gmail. Be careful about generating label names automatically.

**Applying a label to a whole thread is the riskiest thing in the set.** It
changes many messages at once. Try it deliberately, on a conversation that
does not matter, before using it for real.

---

## If you get stuck

The error messages in this world are unhelpful, and that is not a
reflection on you. Almost every problem I had was one of four things: a
path that was not the full path, Claude Desktop not fully quit and
reopened, myself not added as a test user in Google Cloud, or the old
connector still switched on.

Paste the actual error into Claude and ask what it means before trying
anything. Guessing costs more time than asking.

---

## Why bother

Because the tools we are handed are built for the general case, and an
assistant's work is not the general case. Two inboxes is a completely
ordinary requirement for this job and it was not on offer.

Also because building the thing teaches you what it can and cannot do, at a
level that no amount of using someone else's tool ever will. I know exactly
where mine stops being trustworthy. That is worth more than a tool that
does more and tells me less.