**en** • [ru](README.ru.md)

# Smart Money MCP

**Model Context Protocol server for personal finance — log expenses in plain language, track accounts, deposits, budgets and spending, secured by OAuth.**

Smart Money MCP puts your money ledger inside your AI assistant. Connect Claude, ChatGPT, Cursor, VS Code, or a CLI client to Smart Money, then say *"log 4500 on a taxi yesterday from Kaspi"* or ask *"how much did I spend on food this month?"* — the assistant writes to the same ledger the app reads.

- **Server URL:** `https://smart-money.ink/mcp`
- **Transport:** Streamable HTTP
- **Auth:** OAuth 2.1 with PKCE
- **Landing & setup:** [smart-money.ink/claude](https://smart-money.ink/claude)

## Install

Smart Money MCP is a **remote, OAuth-secured** server. There is nothing to install locally. Add this to your MCP client config:

```json
{
  "mcpServers": {
    "smart-money": {
      "type": "http",
      "url": "https://smart-money.ink/mcp"
    }
  }
}
```

**One-click install:**

[![Add to Cursor](https://img.shields.io/badge/Cursor-install-000000?style=for-the-badge&logo=cursor&logoColor=white)](https://cursor.com/en/install-mcp?name=smart-money&config=eyJuYW1lIjoic21hcnQtbW9uZXkiLCJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vc21hcnQtbW9uZXkuaW5rL21jcCJ9)
[![Add to VS Code](https://img.shields.io/badge/VS_Code-install-007ACC?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=smart-money&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fsmart-money.ink%2Fmcp%22%7D)
[![Add to Claude](https://img.shields.io/badge/Claude-connectors-D97757?style=for-the-badge&logo=claude&logoColor=white)](https://claude.ai/settings/connectors)
[![Add to ChatGPT](https://img.shields.io/badge/ChatGPT-connectors-10A37F?style=for-the-badge&logo=openai&logoColor=white)](https://chatgpt.com/settings/connectors)

CLI clients (Claude Code, Gemini CLI, Codex CLI) and manual snippets: see [Supported clients](#supported-clients).

## Quick start

1. Create a Smart Money account at [smart-money.ink](https://smart-money.ink) and start the free trial (see [Plans & access](#plans--access)).
2. Open [smart-money.ink/claude](https://smart-money.ink/claude) and follow the setup path for your client.
3. Use the one-click install, the CLI command, or the manual JSON snippet above.
4. Authorize with OAuth when your client opens the consent screen.
5. Talk to your assistant about money in plain language.

## What you can do from chat

- **💬 Plain-language entry** — `taxi 4500 yesterday kaspi #trip` is parsed into an amount, date, account, currency, tags and category. Amounts like `12k` or `1.2m`, dates like `yesterday` or `3 days ago`, and account names in any script all resolve.
- **📊 Spending answers** — income, expense, savings rate, category breakdown and top merchants for any period.
- **🏦 Accounts & balances** — cards, cash, bank accounts, deposits, credit cards (counted as liabilities), investments and e-wallets. Multi-currency, with rates on the date and totals in your base currency.
- **💰 Deposits with interest** — rate in basis points, accrual frequency, compounding or payout to another account. Interest is computed daily on the real balance, and every accrual carries an idempotency key, so nothing is posted twice.
- **🎯 Budgets** — weekly, monthly or yearly limits with spent, remaining, and an end-of-period forecast.
- **📥 Bank notifications** — paste push-notification text and it becomes transactions; re-importing the same notification does not duplicate it.
- **🏷️ Categories & tags** — flat categories chosen in one step, tags orthogonal to them. An unknown `#tag` is created on the fly; a deleted one is restored instead of duplicated.

## Tool surface

27 tools. Reading and writing are separate tools — no `confirm` or `dryRun` flags — and each one carries a `title` plus `readOnlyHint` / `destructiveHint` annotations, so your client knows which calls deserve a confirmation prompt.

| Category | Tools |
|---|---|
| 👀 **Previews** *(read-only)* | `preview_entry`, `preview_notifications`, `preview_interest` — show the parse before anything is written |
| 💸 **Transactions** | `quick_add`, `add_transaction`, `list_transactions`, `update_transaction`, `delete_transaction`, `import_notifications` |
| 📊 **Reporting** | `summary` — income, expense, savings rate, categories, top merchants for a period |
| 🏦 **Accounts** | `list_accounts`, `create_account`, `update_account`, `delete_account`, `accrue_interest` |
| 🗂️ **Categories** | `list_categories`, `create_category`, `update_category`, `delete_category` |
| 🏷️ **Tags** | `list_tags`, `create_tag`, `update_tag`, `delete_tag` |
| 🎯 **Budgets** | `list_budgets`, `create_budget`, `update_budget`, `delete_budget` |

Deletion is soft: a transaction gets a `deletedAt` and drops out of balances and reports on every device, while its import key stays — so re-importing the same bank notification will not bring it back. An account or category still referenced by transactions cannot be deleted; the connector offers to archive it instead, so history never points at nothing.

For the exact, up-to-date set, run `tools/list` against `https://smart-money.ink/mcp`.

## Plans & access

Smart Money is a paid service with a free trial. The connector reads and writes your real ledger, so it needs an active subscription or trial — there is no anonymous tier.

| | Free trial | Subscription |
|---|---|---|
| **Price** | $0 for 7 days, card required | $7.99 / month |
| Web app, sync, every connector tool | ✅ | ✅ |

Nothing is charged during the trial, and cancelling during it charges nothing. Cancel any time in **Settings → Subscription**. When a subscription lapses the app locks, but records are not deleted: they stay in your browser and can still be exported. Current terms: [smart-money.ink/terms](https://smart-money.ink/terms).

Call a tool without an active subscription and the tool result says so, pointing you at the app's settings.

## Supported clients

- **Claude** (web & desktop) — Settings → Connectors → Add custom connector
- **ChatGPT** — Settings → Connectors → custom MCP connector with OAuth
- **Cursor** — one-click install via deeplink, or `~/.cursor/mcp.json`
- **VS Code** — one-click install via deeplink, or `.vscode/mcp.json`
- **Claude Code (CLI)** — `claude mcp add --transport http smart-money https://smart-money.ink/mcp`
- **Gemini CLI** — `gemini mcp add --transport http smart-money https://smart-money.ink/mcp`
- **Codex CLI** — `codex mcp add smart-money --url https://smart-money.ink/mcp`
- **Generic HTTP MCP client** — point it at the URL and let it complete OAuth discovery

Full per-client instructions: [docs/setup.md](docs/setup.md).

## Cursor plugin

This repository is also a Cursor plugin. It contributes one MCP server (`smart-money`) and no rules, skills, agents, or hooks.

```
.cursor-plugin/plugin.json   ← plugin manifest
mcp.json                     ← the MCP server it contributes
assets/logo.svg              ← plugin logo
```

There is nothing to configure. No API key or environment variable is required: the server advertises OAuth 2.1 metadata, the client registers itself dynamically, and the consent screen opens on first use.

## Example prompts

**Log as you go**
> "taxi 4500 yesterday kaspi #trip"

→ One transaction, parsed and saved: amount, date, account, tag. The preview tool can show the parse first.

**Ask where the money went**
> "How much did I spend on food this month, and how does that compare to my budget?"

→ A category breakdown plus the budget's spent, remaining, and end-of-month forecast.

**Deposits**
> "Post the interest due on my deposits."

→ Interest accrued daily on the actual balance, idempotent: running it twice posts nothing extra.

**Bank notifications**
> *(paste a batch of bank push notifications)* "Turn these into transactions."

→ Parsed into transactions, with already-imported ones skipped.

More: [docs/examples.md](docs/examples.md).

## Authorization & data

Auth is OAuth 2.1 with PKCE. Your assistant gets a token tied to your Smart Money account, and the connector reads and writes **as you** — row-level security and the subscription check apply exactly as they do in the web app. Discovery follows RFC 9728: an unauthenticated call to `/mcp` returns 401 pointing at `https://smart-money.ink/.well-known/oauth-protected-resource/mcp`, and the authorization server is found from there.

Tokens can be revoked at any time from the Smart Money app. OAuth flow details: [docs/oauth.md](docs/oauth.md). Data handling: [smart-money.ink/privacy](https://smart-money.ink/privacy).

## Troubleshooting

Common connection, OAuth, and tool-call errors: [docs/troubleshooting.md](docs/troubleshooting.md).

## Where this server is listed

Registry and directory listings, and how publishing works: [docs/registries.md](docs/registries.md).

## Project links

- Product: [smart-money.ink](https://smart-money.ink)
- Setup page: [smart-money.ink/claude](https://smart-money.ink/claude)
- MCP server: `https://smart-money.ink/mcp`
- Issues: [github.com/ultraza4/smart-money-mcp/issues](https://github.com/ultraza4/smart-money-mcp/issues)

## License

MIT — see [LICENSE](LICENSE).

---

Built by [@ultraza4](https://github.com/ultraza4). Smart Money is a hosted personal-finance service; this repo is documentation and manifests for its public MCP server. Server source is not open.