Emma Transactions MCP Server

A reusable Model Context Protocol server for querying Emma-app transaction exports stored in Google Sheets.

The server is generic: you provide your own Google Sheet URL, published CSV URL, or Sheet ID at runtime. This repository contains no personal transaction data and no hard-coded Sheet IDs.

Features

• list_transactions — list normalized transactions, with filters for category, account, search text, and date range.
• get_spending_summary — totals for income, expenses, net movement, category, account, and month.
• get_metadata — available accounts, categories, currencies, row count, and date range.
• validate_sheet — confirms the sheet can be parsed without returning transaction rows.
• Google Sheets URL helper — accepts a Sheet ID, a normal /edit URL, a /pub?output=csv URL, or an /export?format=csv URL.
• Robust CSV parsing — recognizes common column variants such as Date, Transaction Date, Description, Name, Amount, Value, Category, Account, and Merchant.

Privacy model

This server does not store transaction data. It fetches the configured CSV when a tool is called and returns the requested result to the MCP client.

You still need to treat your Google Sheet URL as sensitive. If you publish a Google Sheet to the web as CSV, anyone with that URL may be able to access the data. Use a private runtime environment and do not commit your real Sheet URL to version control.

Requirements

• Node.js 20+
• An Emma transaction export in Google Sheets, accessible to the process running the MCP server

Current implementation supports unauthenticated CSV access: published-to-web CSV links and Google Sheet export URLs that the runtime can fetch. OAuth/service-account support is intentionally not bundled yet, because credentials for personal finance data need a sharper knife than a README example.

Install

From a checkout:

git clone https://github.com/accesstechnology-mike/emma-transactions-mcp.git
cd emma-transactions-mcp
npm install
npm run build

MCP client configuration

Use an environment variable:

{
  "mcpServers": {
    "emma-transactions": {
      "command": "node",
      "args": ["/absolute/path/to/emma-transactions-mcp/dist/index.js"],
      "env": {
        "EMMA_SHEET_URL": "https://docs.google.com/spreadsheets/d/YOUR_SHEET_ID/pub?output=csv",
        "EMMA_SHEET_GID": "0"
      }
    }
  }
}

Or pass sheet_url in each tool call.

Optional gid selects a specific tab. It defaults to EMMA_SHEET_GID, then 0.

Expected columns

At minimum, the CSV needs:

• date: Date, Transaction Date, Timestamp, or Time
• description: Description, Name, Transaction, Transaction Name, or Title
• amount: Amount, Value, Transaction Amount, Money Out, or Money In

Optional columns include Currency, Category, Account, Merchant, Notes, and Type.

Development

npm install
npm test
npm run build

The test suite uses synthetic fixture rows only. Do not add real transaction exports to tests, issues, screenshots, or docs.

License

MIT