使用说明

项目简介

Toshl 财务 MCP 服务器是一个基于 Model Context Protocol (MCP) 构建的后端应用，旨在桥接 AI 智能体和 Toshl Finance API。它允许 AI 智能体安全地访问用户的 Toshl 财务数据，并利用这些数据进行分析、洞察和提供建议。

主要功能点

资源访问: 提供对 Toshl Finance 账户、类别、标签、预算、用户资料和规划等财务数据的读取访问。
工具集成: 注册并执行多种工具，包括账户管理、类别管理、标签管理、预算管理、用户信息查询、财务分析以及条目（entries）管理等功能，使 AI 智能体能够调用这些工具与 Toshl Finance 进行交互。
数据缓存: 内置缓存机制，减少对 Toshl Finance API 的重复请求，提高响应速度和效率。
详细日志: 提供详细的日志记录，方便开发者进行问题排查和监控服务器运行状态。

安装步骤

克隆仓库:

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

安装依赖: 确保已安装 Node.js (v18.x 或更高版本) 和 npm (v8.x 或更高版本)。然后运行：
```
npm install
```
配置环境变量: 复制 '.env.example' 文件并重命名为 '.env'，然后编辑 '.env' 文件，填入你的 Toshl Finance API Token。获取 Toshl API Token 的步骤：
- 访问 Toshl Developer Apps。
- 创建一个新的个人 Token，在 "Description" 下填写 Token 名称，并在 "Password" 下输入你的账户密码。
'.env' 文件示例:
```
TOSHL_API_TOKEN=你的_Toshl_API_Token
```
构建项目:
```
npm run build
```
运行服务器:
```
npm start
```

服务器配置

以下是 MCP 客户端配置 Toshl 财务 MCP 服务器的示例 JSON 格式配置信息。MCP 客户端需要这份配置才能正确连接和使用此服务器。

{
  "toshl-mcp-server": {
    "command": "node",
    "args": [
      "/path/to/toshl-mcp-server/dist/index.js"  // 请替换为实际的 index.js 文件路径 (通常在项目根目录的 dist 文件夹下)
    ],
    "env": {
      "TOSHL_API_TOKEN": "your-token", // 你的 Toshl API Token，建议在客户端配置中也使用环境变量，此处仅为示例
      "TOSHL_API_BASE_URL": "https://api.toshl.com", // Toshl API 基础 URL，通常无需修改
      "MCP_SERVER_NAME": "toshl-mcp-server", // MCP 服务器名称，可自定义
      "MCP_SERVER_VERSION": "0.1.0", // MCP 服务器版本，与项目版本一致
      "CACHE_TTL": "3600", // 缓存 TTL (Time To Live) 秒数，默认 3600 秒 (1 小时)
      "CACHE_ENABLED": "true", // 是否启用缓存，"true" 或 "false"
      "LOG_LEVEL": "debug" // 日志级别，例如 "debug", "info", "warn", "error"
    },
    "disabled": false, // 是否禁用此服务器，"false" 表示启用
    "autoApprove": [] // 自动批准的请求方法列表，默认为空
  }
}

注意:

请将 '/path/to/toshl-mcp-server/dist/index.js' 替换为你的 'index.js' 文件在服务器上的实际路径。
'TOSHL_API_TOKEN' 强烈建议通过 MCP 客户端的环境变量进行配置，以提高安全性。上述配置示例中 'env.TOSHL_API_TOKEN' 仅为演示配置格式。

基本使用方法

启动服务器: 按照上述 "运行服务器" 步骤启动 Toshl 财务 MCP 服务器。
配置 MCP 客户端: 在你的 MCP 客户端应用中，根据 "服务器配置" 章节的示例，配置连接到 Toshl 财务 MCP 服务器。
使用 AI 智能体: 你的 AI 智能体可以通过 MCP 协议与 Toshl 财务 MCP 服务器进行通信，利用服务器提供的资源和工具来访问和操作 Toshl Finance 数据。

例如，AI 智能体可以请求资源 'toshl://accounts/list' 来获取账户列表，或者调用工具 'account_list' 来执行相同的操作。具体可用的资源和工具请参考服务器提供的 'ListResources' 和 'ListTools' 方法的响应。

关键词