使用说明（Markdown 格式）

项目简介

• 这是一个 MCP（Model Context Protocol）服务器实现，专为 Tiller Money 的 Google Sheets 数据提供只读上下文服务。服务器暴露资源查询工具（账户、交易、分类等），并通过 FastMCP 框架与支持的 MCP 客户端进行交互，完成数据读取与查询任务。

主要功能点

• 资源访问：读取账户、交易、分类等数据（只读，避免写操作）。
• 工具执行：通过定义的工具接口，LLM 客户端可调用获取账户、交易、交易详情、类别等信息的能力。
• 数据源接入：通过 Google Sheets API 读取 Tiller 数据表，包含账户、交易和分类数据，以及可选的月度预算数据。
• 本地执行与隐私保护：在本地环境通过标准输入/输出（stdio）进行通信，数据不外传，且隐藏账户默认排除。
• 配置与认证：使用 Google OAuth2 流程获取凭证，凭证和令牌放在本地 auth 目录，支持自动 token 刷新。

安装步骤

1. 克隆仓库并进入项目目录

• git clone https://github.com/jackstein21/tiller-mcp-server.git
• 进入项目对应路径，确保你本地有 Python 环境。

2. 设置 Python 环境与依赖

• 使用虚拟环境（推荐）并安装依赖：pip install -r requirements.txt

3. Google Sheets API 授权

• 在 Google Cloud Console 创建项目、启用 Google Sheets API、创建 OAuth2 认证凭据并下载 credentials.json，放置于 auth/ 目录下。
• 运行授权脚本进行首次授权并生成 token.json：python auth/auth_setup.py
• 授权完成后，token.json 将用于后续访问并会自动刷新。

4. 配置 Claude Desktop（或等效 MCP 客户端）

• 在 Claude Desktop 的配置中添加 MCP 服务器信息，示例配置需包含服务器名称、启动命令和参数等信息（见下方“服务器配置”说明）。
• 必要环境变量：将你的 Tiller 表格 ID 设置为 TILLER_SHEET_ID（Claude Desktop 的 env 配置或运行环境变量中设置）。此 ID 指向你要查询的 Google Sheets 表格。

5. 启动服务器

• 使用如下命令在本地启动服务器（路径请按实际项目路径调整）： python src/tiller_mcp_server/server.py
• 启动后，服务器将监听并等待来自 MCP 客户端的请求。

6. 测试与调试

• 直接在终端测试：运行 python src/tiller_mcp_server/server.py，查看日志输出。
• 调试时可查看 auth/token.json 的自动刷新以及 TILLER_SHEET_ID 是否正确设置。

服务器配置（MCP 客户端使用，但不需要客户端理解） 以下为示例配置（以 JSON 形式描述，供 MCP 客户端读取，用于启动与连接该 MCP 服务器）。请将命名、路径和参数替换为你实际的部署信息。MCP 客户端本身不需要理解此配置的内部实现，仅需读取 server_name、command、args 等字段来启动服务器进程。

{ "server_name": "Tiller MCP Server", "command": "python", "args": [ "src/tiller_mcp_server/server.py" ], "env": { "TILLER_SHEET_ID": "your_spreadsheet_id_here" } // 说明： // - server_name：显示给用户的服务器名称 // - command：用于启动 MCP 服务器的命令（可使用系统 Python 解释器路径） // - args：启动命令的参数，通常为服务器脚本的相对/绝对路径 // - env：必要的环境变量，例如 TILLER_SHEET_ID，用于指定要查询的 Tiller 表格 // 注意：MCP 客户端不需要对上述配置做修改，实际使用时请在 Claude Desktop 或相应客户端的配置界面填写具体路径和变量 }