Claude Code setup guide

Connect Gmail and MatchLedger to Claude Code

Two connections, about ten minutes, and your terminal can go and get a statement out of your own inbox and turn it into a clean import file. This page sets up both halves. The inbox-to-Monarch walkthrough is what you run once they are wired.

They connect in different ways

Gmail is reached through an ordinary command line tool that Claude Code runs in your shell. There is no MCP server for it and nothing to add to a config file. MatchLedger is the MCP half: one command, then a browser consent screen. Knowing which is which saves you looking for a Gmail connector that does not exist.

Part one: Gmail

The Google Workspace CLI, published by Google as @googleworkspace/cli, exposes Gmail, Drive, Sheets, Calendar and the rest of the Workspace APIs as a single command called gws. Claude Code drives it the same way you would: by running it and reading the JSON.

Install the CLI.

Node 18 or newer:

Install

npm install -g @googleworkspace/cli

Create an OAuth client.

Google will not hand a third party CLI access to your mail, so you supply your own OAuth client. The CLI can build one for you, which is the short path:

Guided setup

gws auth setup --login

This one needs the gcloud CLI installed and signed in, because it creates a Google Cloud project, enables the Workspace APIs on it, and registers a desktop OAuth client. It is free, and the project exists only to hold that client. If you would rather not install gcloud, create the OAuth client by hand in the Google Cloud console and point the CLI at the downloaded JSON with GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE.

Sign in and pick your scopes.

If you used the guided setup with --login you are already through this. Otherwise:

gws auth login --services gmail,drive,sheets

A browser opens, you approve, and the refresh token is encrypted into your OS keyring. Limiting the services keeps the grant small. Three are enough for statement work:

Service	What it buys you
gmail	Search the inbox, read a message, pull an attachment down to disk
drive	Upload a file, convert a CSV to a Google Sheet, share it
sheets	Read and write cells in a spreadsheet you already have

Add --readonly if you want the CLI able to read your mail and nothing else. Statement retrieval never needs to send, delete or label anything.

Check it works.

Auth state

gws auth status

Find recent PDF attachments

gws gmail users messages list --params '{"userId":"me","q":"has:attachment filename:pdf newer_than:60d"}' --format table

The second one is the real test: a Gmail search string, the same one you would type into the search box, returning message IDs. If that prints a table, Claude Code can now find your statements.

Keeping work and personal mail apart

Every credential the CLI holds lives in one config directory, so a second account is a second directory. Sign in again with the variable set:

Second account

GOOGLE_WORKSPACE_CLI_CONFIG_DIR="$HOME/.config/gws-personal" gws auth login

Then prefix any later command with the same variable to choose which mailbox it reads. Worth doing before you point an agent at an inbox: the one it cannot see is the one it cannot leak.

Part two: MatchLedger

MatchLedger runs a native MCP server, so this half is a single line with no package to install and no API key to paste.

Add the server.

Claude Code

claude mcp add --transport http matchledger https://app.matchledger.ai/mcp

Add --scope user if you want it available in every project rather than the current one.

Authenticate.

Run /mcp inside Claude Code, pick MatchLedger, and choose to authenticate. Your browser opens a MatchLedger sign in page. Sign in with Google or email, or create the account right there and accept the terms. Every account runs at Professional capacity while the beta is on, whichever plan you pick later. There is no credit card and no trial clock.

Pick which set of books to connect, review the permissions, and click Allow. These are the six shown on the consent screen:

Permission	What it allows
documents:write	Upload bank statements, credit-card statements and ledger reports
reconciliations:write	Run reconciliations
reconciliations:read	Read reconciliation results, matches and uploaded documents
exports:write	Create and download exports
usage:read	Read your plan and usage meters
webhooks:manage	Manage webhook subscriptions

Organization is what MatchLedger calls one set of books, and the connection is scoped to the single one you pick. If you keep several, connect the one you want the terminal working in and reconnect later to change it.

Check it works.

Server list

claude mcp list

MatchLedger should be listed and connected. Then ask for something only the server can answer:

In Claude Code

Ask MatchLedger how much of my monthly plan I have used.

You should get back your plan, the organization name, and the used, remaining and limit values for line items and reconciliation jobs. Compare them with the Plan & Usage card in the web app. If they agree, the connection is live and pointed at the books you expect.

A statement upload is a background job, so expect repeated tool calls.

MatchLedger extracts in the background and Claude Code polls until it finishes, seconds for a short CSV and a few minutes for a long scanned PDF. Approving each poll individually gets old fast. Allow the MatchLedger tools for the session and let the run finish on its own.

Both halves at once

One prompt that only works if each connection is good, which makes it a decent final check:

In Claude Code

Search my Gmail for credit card statement PDFs from the last 60 days, list what you find, then tell me which MatchLedger organization you are connected to.

Claude Code shells out to the Workspace CLI for the first half and calls the MCP server for the second. If both answer, you are ready to run the real thing.

Next: pull a statement out of your inbox and into Monarch without opening a browser.

Read the walkthrough

Common questions

Is there a Gmail MCP server for Claude Code?

Not one you need here. Gmail is reached through the Google Workspace CLI, an ordinary command line tool that Claude Code runs in your shell like any other command, so there is nothing to add to an MCP config for it. Only the MatchLedger half of this setup is MCP.

How do I connect MatchLedger to Claude Code?

Run claude mcp add --transport http matchledger https://app.matchledger.ai/mcp, then run /mcp inside Claude Code and choose to authenticate. Your browser opens a MatchLedger sign-in page, you pick which set of books to connect, and you approve the permissions. There is no API key to paste.

Why does the Google Workspace CLI need gcloud?

Only for the guided setup. Google will not hand a third-party CLI access to your mail, so you supply your own OAuth client, and gws auth setup creates one for you by making a free Google Cloud project and registering a desktop client on it. If you would rather not install gcloud, create the OAuth client by hand in the Google Cloud console and point the CLI at the downloaded JSON instead.

Can I keep work and personal mail separate?

Yes. Every credential the CLI holds lives in one config directory, so a second account is a second directory: set GOOGLE_WORKSPACE_CLI_CONFIG_DIR to a new path and sign in again, then prefix later commands with the same variable to choose which mailbox they read. The inbox an agent cannot see is the one it cannot leak.

Does the CLI need write access to my inbox?

No. Retrieving statements only reads. Pass --readonly when you sign in and the grant covers reading your mail and nothing else, with no ability to send, delete or label.

Other clients

The MatchLedger half of this works the same way from the chat apps. There is a click-by-click guide for Claude Desktop, one for ChatGPT, and a short quick start for Claude Code and Codex.

Claude and Claude Code are products of Anthropic. Gmail, Google Drive, Google Sheets and the Google Workspace CLI are products of Google. MatchLedger is not affiliated with or endorsed by either.