Toshl MCP Server

An MCP (Model Context Protocol) server for integrating Toshl Finance with AI agents.

Overview

The Toshl MCP Server provides a bridge between AI agents and the Toshl Finance API. It allows AI agents to access financial data from Toshl, analyze it, and provide insights and advice based on the data.

Features

• READ access to Toshl Finance API endpoints:

  • Accounts
  • Categories
  • Tags
  • Budgets
  • User information
  • Planning

• MCP Resources:

  • List accounts
  • Get account details
  • List categories
  • Get category details
  • List tags
  • Get tag details
  • Create tag
  • List budgets
  • Get budget details
  • Get budget history
  • Get user profile
  • Get account summary
  • List entries

• MCP Tools:

  • Account tools (list accounts, get account details)
  • Category tools (list categories, get category details, create category, update category, delete category)
  • Tag tools (list tags, get tag details, create tag, update tag, delete tag)
  • Budget tools (list budgets, get budget details, get budget history)
  • User tools (get profile, get summary, get payment types, get payments)
  • Entry tools (list entries, get entry details, get entry sums, get entry timeline, create entry, update entry, delete entry, manage entries, split entry, undo split)
  • Analysis tools (analyze spending by category, analyze budget performance, analyze account balances)

Prerequisites

• Node.js (v18.x or higher)
• npm (v8.x or higher)
• Toshl Finance API token

Get API Token

1. go to https://developer.toshl.com/apps/
2. create new personal token. Insert name for token under “Description” and your account password under “Password”

Installation

1. Clone the repository:

git clone https://github.com/hktari/toshl-mcp-server.git
cd toshl-mcp-server

2. Install dependencies:

npm install

3. Create a .env file based on the .env.example file:

cp .env.example .env

4. Edit the .env file and add your Toshl API token:

TOSHL_API_TOKEN=your_api_token

Building

Build the project:

npm run build

Running

Start the server:

npm start

Configure MCP server

The server speaks MCP over stdio. Point your client at dist/index.js and pass TOSHL_API_TOKEN in its environment — step-by-step instructions for Claude Code, OpenCode, and Codex CLI are in docs/mcp-clients.md.

For any other client that takes a generic mcpServers config:

{
    "mcpServers": {
        "toshl": {
            "command": "node",
            "args": ["/absolute/path/to/toshl-mcp-server/dist/index.js"],
            "env": {
                "TOSHL_API_TOKEN": "your-token"
            }
        }
    }
}

Remote use (Streamable HTTP)

stdio is the default and needs nothing below. To reach the server from clients that can’t