Toshl MCP 服务器

一个用于集成 Toshl Finance 与 AI 代理的 MCP (模型上下文协议) 服务器。

概述

Toshl MCP 服务器提供了一个连接 AI 代理和 Toshl Finance API 的桥梁。它允许 AI 代理访问 Toshl 的财务数据，分析数据，并基于数据提供见解和建议。

功能

• READ 访问 Toshl Finance API 端点：

  • 账户
  • 类别
  • 标签
  • 预算
  • 用户信息
  • 规划

• MCP 资源：

  • 列出账户
  • 获取账户详情
  • 列出类别
  • 获取类别详情
  • 列出标签
  • 获取标签详情
  • 列出预算
  • 获取预算详情
  • 获取预算历史
  • 获取用户资料
  • 获取账户摘要
  • 列出条目

• MCP 工具：

  • 账户工具（列出账户，获取账户详情）
  • 类别工具（列出类别，获取类别详情）
  • 标签工具（列出标签，获取标签详情）
  • 预算工具（列出预算，获取预算详情，获取预算历史）
  • 用户工具（获取资料，获取摘要，获取支付类型，获取支付信息）
  • 条目工具（列出条目，获取条目详情，获取条目总和，获取条目时间线，创建条目，更新条目，删除条目，管理条目）
  • 分析工具（按类别分析支出，分析预算表现，分析账户余额）

前提条件

• Node.js (v18.x 或更高版本)
• npm (v8.x 或更高版本)
• Toshl Finance API 令牌

获取 API 令牌

1. 前往 https://developer.toshl.com/apps/
2. 创建新的个人令牌。在“描述”下插入令牌名称，并在“密码”下输入您的账户密码。

安装

1. 克隆存储库：

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

2. 安装依赖项：

npm install

3. 基于 .env.example 文件创建 .env 文件：

cp .env.example .env

4. 编辑 .env 文件并添加您的 Toshl API 令牌：

TOSHL_API_TOKEN=your_api_token

构建

构建项目：

npm run build

运行

启动服务器：

npm start

配置 MCP 服务器

 "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": []
    }

开发

在开发模式下运行服务器：

npm run dev

文档

• API 概述
• 身份验证
• 账户
• 条目
• 转账

项目结构

toshl-mcp-server/
├── src/
│   ├── index.ts                 # 入口点
│   ├── server/                  # MCP 服务器实现
│   │   └── server.ts            # 主服务器类
│   ├── api/                     # Toshl API 客户端
│   │   ├── toshl-client.ts      # 基础 API 客户端
│   │   ├── auth.ts              # 身份验证模块
│   │   └── endpoints/           # 特定于端点的客户端
│   │       ├── accounts.ts      # 账户 API 客户端
│   │       ├── categories.ts    # 类别 API 客户端
│   │       ├── tags.ts          # 标签 API 客户端
│   │       ├── budgets.ts       # 预算 API 客户端
│   │       ├── entries.ts       # 条目 API 客户端
│   │       ├── me.ts            # 用户 API 客户端
│   │       └── planning.ts      # 规划 API 客户端
│   ├── resources/               # MCP 资源处理程序
│   │   ├── account-resources.ts # 账户资源
│   │   ├── category-resources.ts# 类别资源
│   │   ├── tag-resources.ts     # 标签资源
│   │   ├── budget-resources.ts  # 预算资源
│   │   └── user-resources.ts    # 用户资源
│   ├── tools/                   # MCP 工具处理程序
│   │   ├── account-tools.ts     # 账户工具
│   │   ├── category-tools.ts    # 类别工具
│   │   ├── tag-tools.ts         # 标签工具
│   │   ├── budget-tools.ts      # 预算工具
│   │   ├── user-tools.ts        # 用户工具
│   │   └── analysis-tools.ts    # 财务分析工具
│   └── utils/                   # 实用函数
│       ├── cache.ts             # 缓存实用程序
│       ├── error-handler.ts     # 错误处理实用程序
│       ├── logger.ts            # 日志记录实用程序
│       └── types.ts             # TypeScript 类型定义
├── dist/                        # 编译后的 JavaScript 文件
├── .env                         # 环境变量
├── .env.example                 # 示例环境变量
├── package.json                 # 项目依赖项
├── tsconfig.json                # TypeScript 配置
└── README.md                    # 项目文档

配置

可以使用环境变量配置服务器：

• TOSHL_API_TOKEN: 您的 Toshl API 令牌
• TOSHL_API_BASE_URL: Toshl API 的基本 URL（默认：https://api.toshl.com）
• MCP_SERVER_NAME: MCP 服务器的名称（默认：toshl-mcp-server）
• MCP_SERVER_VERSION: MCP 服务器的版本（默认：0.1.0）
• CACHE_TTL: 缓存数据的生存时间，以秒为单位（默认：3600）
• CACHE_ENABLED: 是否启用缓存（默认：true）
• LOG_LEVEL: 日志记录级别（默认：info）

许可证

MIT