# Tally MCP server

Ask your AI agent (Claude, Cursor) about the subscriptions you turn into tokenized stock — "how much did I earn this month?" — instead of typing commands.

```
claude mcp add tally -s local -- npx github:TallyMoneyRH/tally-mcp
```

## Tools

| Tool | Kind | What it does |
|---|---|---|
| `tally_connect(email, wallet?)` | **write** | Creates a new forwarding address for the email + returns Gmail setup steps. Only call when the user actually wants to connect. |
| `tally_status(addr_id)` | read | Rewards this month, tier multiplier, settlement status, claimable count. |
| `tally_verification(addr_id)` | read | The Gmail forwarding confirmation code, once it arrives. |
| `tally_claim_calldata(addr_id)` | read | `claim()` calldata for each voucher, to submit from the user's own wallet. |

## What it accesses

- **Your inbox:** nothing. Tally never logs into your inbox. A Gmail filter scoped to your subscription senders forwards *only* those receipts to your Tally address; Tally reads merchant, amount and date from those.
- **Your keys:** the server never asks for or handles a private key. `tally_claim_calldata` returns public calldata only — signing happens in your own wallet.
- **Locally:** no filesystem access, no shell execution. Talks only to `https://tallymoney.app` (override with `TALLY_API`). One legitimate dependency: `@modelcontextprotocol/sdk` (+ `zod`).
- **Revoke any time:** delete the Gmail filter and forwarding address.

MIT licensed.