Toshl MCP

Author: Fedele Mantuano

MCP server that connects Claude Desktop to the Toshl Finance API. Transport: stdio. Auth: Toshl Personal Token via HTTP Basic Auth.

Tools

Tool	Description
get_accounts	List accounts with balances
get_entries	List transactions with date range, category, tag filters
get_categories	List expense/income categories
get_tags	List tags
get_budgets	List budgets with current spending status
get_summary	Toshl summary totals and averages for a date range

get_accounts

Returns all Toshl accounts, including archived accounts. Each result includes the account name, current and initial balances, currency, type, and status.

get_entries

Returns transactions between the required inclusive from_date and to_date arguments, both in YYYY-MM-DD format. The optional category argument filters by category ID, while tags accepts comma-separated tag IDs.

Each entry includes its amount, currency, date, description, account, category, and tags.

get_categories

Returns expense and income categories. Use the optional type argument with expense or income to return only that category type; omit it to return both.

Each category includes its ID, name, type, and deletion status.

get_tags

Returns all user-defined Toshl tags. Each tag includes its ID, name, and whether it applies to expenses or income.

get_budgets

Returns all budgets with their limits and current spending status. Each budget includes its ID, name, limit, amount spent, currency, and inclusive start and end dates.

get_summary

Returns expense and income aggregates from Toshl's summary endpoint. The from_date and to_date arguments use YYYY-MM-DD and are both inclusive. Use the optional currency argument to request a specific output currency; when omitted, Toshl uses the user's main currency.

The result contains from_date, to_date, total_expenses, total_income, net, avg_daily_expense, period_days, and entry_count. entry_count combines Toshl's expense and income counts, and the daily average uses the inclusive number of days in the range.

Requirements

• Python 3.11 or newer
• uv
• Toshl Personal Token — generate at Toshl → Profile → Apps & tokens

Claude Desktop Configuration

1. Install uv (if not already installed):

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install the package into a dedicated virtualenv:

With uv:

uv venv ~/.toshl-mcp
uv pip install --python ~/.toshl-mcp/bin/python toshl-mcp

Or with pip:

python3 -m venv ~/.toshl-mcp
~/.toshl-mcp/bin/pip install toshl-mcp

3. Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "toshl": {
      "command": "/Users/<your-username>/.toshl-mcp/bin/toshl-mcp",
      "env": {
        "TOSHL_TOKEN": "<your-toshl-personal-token>"
      }
    }
  }
}

Replace <your-username> with your macOS username (run whoami to confirm).

Updating

Upgrade in place — use the same tool you installed with.

With uv:

uv pip install --python ~/.toshl-mcp/bin/python --upgrade toshl-mcp

Or with pip:

~/.toshl-mcp/bin/pip install --upgrade toshl-mcp

Then restart Claude Desktop. It spawns the server process at startup, so a running instance keeps the old version until it is restarted.

Check the installed version:

~/.toshl-mcp/bin/python -c "import toshl_mcp; print(toshl_mcp.__version__)"

Compare it against the latest release on PyPI.

claude_desktop_config.json does not need to change — the path to the executable stays the same across upgrades.

Note: uv venv does not install pip into the virtualenv, so ~/.toshl-mcp/bin/pip exists only if you used the pip install path.

Environment Variables

Variable	Required	Default	Description
TOSHL_TOKEN	Yes	—	Toshl Personal Token
LOG_LEVEL	No	WARNING	Logging level (DEBUG, INFO, WARNING, ERROR)

Development

Setup

1. Install uv (if not already installed):

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install all dependencies:

uv sync --all-groups

3. Install pre-commit hooks:

make pre-commit

Make commands

make install     # install dependencies
make lint        # check code
make lint-fix    # check and auto-fix
make format      # format code
make test        # run tests
make test-cov    # run tests with coverage report
make pre-commit  # run all pre-commit hooks
make dev         # start MCP inspector (requires .env)
make clean       # remove build artifacts and caches

Note: Stage changes with git add before running make pre-commit — unstaged files are ignored.

Testing with MCP Inspector

The MCP Inspector lets you call tools interactively in a browser without Claude Desktop.

1. Create a .env file in the project root:

TOSHL_TOKEN=your-personal-token-here

2. Start the inspector:

make dev

3. Open http://localhost:6274 in your browser.

4. Connect — click Connect in the top bar.

5. Test tools:

• Click Tools in the left sidebar
• Click List Tools to see all six tools
• Select a tool (e.g. get_accounts), fill in any parameters, click Run