MCP connection

The Model Context Protocol (MCP) lets AI agents interact directly with your Tally data — listing budgets, creating transactions, searching spending, and more — all through natural conversation.

Authentication

Tally MCP uses OAuth 2.1 for authentication. When you connect for the first time, your MCP client will open a browser where you sign in with your existing Tally account (Google or Apple). No API keys are needed.

Quick install

From any terminal, with Node.js 18+ installed.

All supported apps (Cursor, OpenCode, Claude Code, Claude Desktop) in one go:

npx -y tally-mcp-install --all

Cursor only (default):

npx -y tally-mcp-install

Restart each app you configured. You'll be prompted to sign in via OAuth on first use. Add flags to include more clients: --with-opencode, --with-claude-code, --with-claude; or use --opencode-only / --claude-code-only for a single client.

Connect Claude Desktop

Open Claude Desktop settings
Navigate to the MCP Servers section
Add a new server with this configuration:

{
  "mcpServers": {
    "tally": {
      "url": "https://tallybudget.app/api/mcp"
    }
  }
}

Save and restart Claude Desktop
On first use, you'll be prompted to sign in — then Tally tools will appear in your conversation

Connect Cursor

Fastest: use Quick install above (--all configures Cursor along with OpenCode, Claude Code, and Claude Desktop).

Manual:

Open your Cursor MCP config at ~/.cursor/mcp.json
Add the Tally server:

{
  "mcpServers": {
    "tally": {
      "url": "https://tallybudget.app/api/mcp"
    }
  }
}

Restart Cursor — you'll sign in via OAuth on first use

Connect OpenCode

OpenCode reads MCP settings under mcp in opencode.json or opencode.jsonc — often ~/.config/opencode/opencode.json for global config (OpenCode config).

Quick install:

npx -y tally-mcp-install --with-opencode

OpenCode only (no Cursor mcp.json):

npx -y tally-mcp-install --opencode-only

Restart OpenCode after installing.

Manual config — use a remote entry (OpenCode MCP — remote):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tally": {
      "type": "remote",
      "url": "https://tallybudget.app/api/mcp",
      "enabled": true
    }
  }
}

Connect Claude Code

Claude Code is Anthropic’s CLI; it stores user-scope MCP servers in ~/.claude.json under mcpServers, using type: "http" for remote servers.

Quick install:

npx -y tally-mcp-install --with-claude-code

Or use --all to include Cursor, OpenCode, Claude Code, and Claude Desktop together.

Official CLI (if you have claude on your PATH):

claude mcp add --transport http --scope user \
  tally https://tallybudget.app/api/mcp

Manual ~/.claude.json:

{
  "mcpServers": {
    "tally": {
      "type": "http",
      "url": "https://tallybudget.app/api/mcp"
    }
  }
}

Connect other MCP clients

Any MCP client that supports streamable HTTP transport with OAuth 2.1 can connect to Tally:

Server URL: https://tallybudget.app/api/mcp
Method: POST
Authentication: OAuth 2.1 (authorization code + PKCE), discovered via /.well-known/oauth-protected-resource

Available tools

Once connected, these tools are available to the AI agent:

Budgets

Tool	Description
`tally_list_budgets`	List budgets with optional filters (status, household, pagination)
`tally_get_budget`	Get a single budget by ID
`tally_create_budget`	Create a new budget
`tally_update_budget`	Update a budget's name, dates, or income
`tally_delete_budget`	Soft-delete a budget
`tally_get_budget_summary`	Get a budget with full category breakdown and spending summary

Transactions

Tool	Description
`tally_list_transactions`	List transactions with filters (budget, category, date range, sort)
`tally_get_transaction`	Get a single transaction by ID
`tally_create_transaction`	Create a new transaction
`tally_update_transaction`	Update a transaction
`tally_delete_transaction`	Soft-delete a transaction
`tally_search_transactions`	Search transaction details by text query

Tool	Description
`tally_list_categories`	List categories for a budget
`tally_create_category`	Create a new category in a budget

Security

No API keys or secrets are stored in your config files — authentication is handled via OAuth 2.1
On first connection, you sign in through Tally's website using your existing Google/Apple account
Access tokens are short-lived and managed by your MCP client
All data access is scoped to your account using the same permission system as the REST API
You can revoke access at any time via the developer portal