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.

Related MCP server: Gmail AutoAuth MCP Server

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:

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 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:

   pip install -r requirements.txt

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

   {
     "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