An MCP (Model Context Protocol) server for integrating Toshl Finance with AI agents.
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.
-
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
- 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)
- Tag tools (list tags, get tag details)
- 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)
- Analysis tools (analyze spending by category, analyze budget performance, analyze account balances)
- Node.js (v18.x or higher)
- npm (v8.x or higher)
- Toshl Finance API token
- go to https://developer.toshl.com/apps/
- create new personal token. Insert name for token under "Description" and your account password under "Password"
- Clone the repository:
git clone https://github.com/yourusername/toshl-mcp-server.git
cd toshl-mcp-server- Install dependencies:
npm install- Create a
.envfile based on the.env.examplefile:
cp .env.example .env- Edit the
.envfile and add your Toshl API token:
TOSHL_API_TOKEN=your_api_token
Build the project:
npm run buildStart the server:
npm start "toshl-mcp-server": {
"command": "node",
"args": [
"/root/source/personal/toshl-mcp-server/dist/index.js"
],
"env": {
"TOSHL_API_TOKEN": "your-token",
"TOSHL_API_BASE_URL": "https://api.toshl.com",
"MCP_SERVER_NAME": "toshl-mcp-server",
"MCP_SERVER_VERSION": "0.1.0",
"CACHE_TTL": "3600",
"CACHE_ENABLED": "true",
"LOG_LEVEL": "debug"
},
"disabled": false,
"autoApprove": []
}
Run the server in development mode:
npm run devtoshl-mcp-server/
├── src/
│ ├── index.ts # Entry point
│ ├── server/ # MCP server implementation
│ │ └── server.ts # Main server class
│ ├── api/ # Toshl API client
│ │ ├── toshl-client.ts # Base API client
│ │ ├── auth.ts # Authentication module
│ │ └── endpoints/ # Endpoint-specific clients
│ │ ├── accounts.ts # Accounts API client
│ │ ├── categories.ts # Categories API client
│ │ ├── tags.ts # Tags API client
│ │ ├── budgets.ts # Budgets API client
│ │ ├── entries.ts # Entries API client
│ │ ├── me.ts # User API client
│ │ └── planning.ts # Planning API client
│ ├── resources/ # MCP resource handlers
│ │ ├── account-resources.ts # Account resources
│ │ ├── category-resources.ts# Category resources
│ │ ├── tag-resources.ts # Tag resources
│ │ ├── budget-resources.ts # Budget resources
│ │ └── user-resources.ts # User resources
│ ├── tools/ # MCP tool handlers
│ │ ├── account-tools.ts # Account tools
│ │ ├── category-tools.ts # Category tools
│ │ ├── tag-tools.ts # Tag tools
│ │ ├── budget-tools.ts # Budget tools
│ │ ├── user-tools.ts # User tools
│ │ └── analysis-tools.ts # Financial analysis tools
│ └── utils/ # Utility functions
│ ├── cache.ts # Caching utilities
│ ├── error-handler.ts # Error handling utilities
│ ├── logger.ts # Logging utilities
│ └── types.ts # TypeScript type definitions
├── dist/ # Compiled JavaScript files
├── .env # Environment variables
├── .env.example # Example environment variables
├── package.json # Project dependencies
├── tsconfig.json # TypeScript configuration
└── README.md # Project documentation
The server can be configured using environment variables:
TOSHL_API_TOKEN: Your Toshl API tokenTOSHL_API_BASE_URL: The base URL for the Toshl API (default: https://api.toshl.com)MCP_SERVER_NAME: The name of the MCP server (default: toshl-mcp-server)MCP_SERVER_VERSION: The version of the MCP server (default: 0.1.0)CACHE_TTL: Time to live for cached data in seconds (default: 3600)CACHE_ENABLED: Whether caching is enabled (default: true)LOG_LEVEL: Logging level (default: info)
MIT