# gmail-invoice-mcp

An MCP server that pulls invoice and receipt attachments out of Gmail and drops them
straight into an accounting folder.

## The problem

Bookkeeping for a small company means opening dozens of emails a month, downloading a PDF
from each one, renaming it, and filing it. The standard Gmail integrations for AI assistants
can read a message, but none of them can hand you the attachment — so the one step that
actually takes time stays manual.

## What it does

Four tools, exposed over the Model Context Protocol, so an assistant can do the whole
fetch-and-file pass in one instruction:

| Tool | What it does |
|---|---|
| `search_with_attachments` | Finds messages matching a Gmail query that carry attachments |
| `list_attachments` | Lists the attachments on one message with names, types and sizes |
| `get_attachment` | Downloads a single attachment, optionally straight to a path |
| `save_attachments_to_folder` | Bulk-saves every attachment matching a query into one folder |

A month of supplier invoices is then a single request: *"save every PDF from these five
senders since 1 June into the bookkeeping folder"*.

## Stack

Python · [MCP](https://modelcontextprotocol.io) FastMCP · Gmail API · Google OAuth 2.0
(read-only scope, token cached locally)

## Result

Collecting one month of supplier invoices for a Norwegian AS went from an hour of manual
downloading to a single instruction. It has been running in production bookkeeping since
early 2026.

## Setup

1. Create a Google Cloud project, enable the Gmail API, and configure an OAuth consent screen.
2. Download the OAuth client credentials as `credentials.json`.
3. Install dependencies:

   ```bash
   pip install -r requirements.txt
   ```

4. Point the server at your credentials and register it with your MCP client:

   ```json
   {
     "mcpServers": {
       "gmail-invoice": {
         "command": "python",
         "args": ["src/server.py"],
         "env": {
           "GMAIL_CREDENTIALS_PATH": "/path/to/credentials.json",
           "GMAIL_TOKEN_PATH": "/path/to/token.json"
         }
       }
     }
   }
   ```

On first run the server opens a browser for authorization and caches the token at
`GMAIL_TOKEN_PATH`. The scope is `gmail.readonly` — the server can read and download,
never send or delete.

## Security

`credentials.json` and `token.json` are secrets. They are excluded in `.gitignore`
and must never be committed.

## License

MIT