home / mcp / toshl mcp server

Toshl MCP Server

Provides read access to Toshl Finance data via MCP resources and tools for agents to analyze and act on financial information.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "hktari-toshl-mcp-server": {
      "command": "node",
      "args": [
        "/root/source/personal/toshl-mcp-server/dist/index.js"
      ],
      "env": {
        "CACHE_TTL": "3600",
        "LOG_LEVEL": "debug",
        "CACHE_ENABLED": "true",
        "MCP_SERVER_NAME": "toshl-mcp-server",
        "TOSHL_API_TOKEN": "your_token_placeholder",
        "MCP_SERVER_VERSION": "0.1.0",
        "TOSHL_API_BASE_URL": "https://api.toshl.com"
      }
    }
  }
}

You run a Toshl MCP Server to bridge AI agents with the Toshl Finance API. It gives read access to Toshl data and exposes a wide set of MCP resources and tools so agents can list, inspect, and analyze accounts, categories, budgets, entries, and more, all in an authenticated and scalable way.

How to use

You connect an MCP client to the Toshl MCP Server to request data and run analyses. Start the local server with the provided runtime command, then configure your MCP client to point to the server. Use the available resources to list accounts, categories, budgets, and entries, or invoke analysis tools to understand spending patterns, budget performance, and account balances. The server exposes resources for each Toshl API area and bundled tools that perform common data retrieval and calculations.

Typical usage patterns include: creating an entry, retrieving an account summary, listing budgets, and running spending analyses by category. You can also obtain user profile information and budget history to inform decision-making. To maximize performance, rely on the server’s caching options and appropriate log level settings.

How to install

Prerequisites you must have before installation.

# Prerequisites
node -v  # ensure Node.js 18.x or higher
npm -v   # ensure npm 8.x or higher

# Step 1: Clone the repository
git clone https://github.com/yourusername/toshl-mcp-server.git
cd toshl-mcp-server

# Step 2: Install dependencies
npm install

# Step 3: Create and configure environment
cp .env.example .env
# Edit .env and set your Toshl API token and other required vars

Step 4: Run the server in development or start mode as described in the configuration section.

Additional content

Configuration and runtime details are important for a reliable setup. You’ll provide token-based authentication to Toshl and specify base URLs, cache settings, and log levels to control performance and observability.

Available tools

Account tools

Manage accounts: list accounts and get account details.

Category tools

Manage categories: list categories and get category details.

Tag tools

Manage tags: list tags and get tag details.

Budget tools

Manage budgets: list budgets, get details, and retrieve history.

Entry tools

List entries, get entry details, sums, timeline, and CRUD operations; manage entries.

Analysis tools

Analyze spending by category, analyze budget performance, and analyze account balances.