Job-application tracker

tracker-mcp

用于跟踪求职申请的电子表格的 MCP 服务：Excel、 CSV 或 Google Sheets。将它连接到 Claude（或任何 MCP 客户端），助手 就会为你维护跟踪表：根据表格回答问题、提醒你哪些事项到期，并记录 发生的情况；每次修改都会先征得你的同意。

По-русски：如何连接。

你： 本周有哪些待跟进事项？

Claude： 有三项。Acme（9 月 17 日申请）：在 LinkedIn 上联系 Sarah Kim，已经逾期 两天。Globex：周四到期，还没有联系。Initech：周五到期。

你： 我周一之前联系不上 Globex 的任何人。把日期往后推。

Claude： 第 8 行 · Globex — 工程主管。跟进日期：10 月 23 日 → 10 月 27 日； 跟进记录：+“跟进日期改为 2026-10-27：尚未联系”。要写入吗？

你： 是。

Claude： 完成。已先创建备份；说“撤销”即可还原。

还可以问：“哪个渠道给我带来的回复最多？”、“Initech 拒绝了我”、“我今天通过内推申请了 Hooli”、“关闭所有 45 天内没有回复的申请”。

为什么需要 MCP 服务？Claude 不能直接做这些吗？

可以，只要你设置好。Claude 可以读取你附上的电子表格；如果它能访问你的 文件（例如使用 Claude Code，或在电脑上的某个文件夹中运行 Claude），就能编写一小段 代码来编辑跟踪表；在 claude.ai 中，Google Sheets 连接器也允许它直接编辑 Google Sheet。给它清晰的说明 （跟踪表的位置、每列的含义、如何计算跟进次数，以及“每次写入前先备份并征求我的同意”）， 它就能正常工作：tracker-mcp 正是从这样的设置中发展而来的。区别在于规则存放在哪里：是在模型读取并遵循的说明中，还是在负责执行这些规则的程序中。

	使用你所写说明的 Claude	tracker-mcp
了解你的跟踪表	根据你写的说明，或在每次聊天时重新推断	根据列标题和下拉选项学习一次，并保存在配置中
跟进日期、未回复的申请、申请漏斗	模型每次都编写代码来处理	规则固定在经过测试的代码中：每次答案都相同
写入前征求同意	说明中要求这样做且模型遵循时	服务会拒绝任何未经你确认的写入
备份、撤销、修改日志	模型创建时才有	每次写入都会生成
新行中的下拉选项和公式	取决于为该次修改编写的代码	每次都会扩展到新行
Excel 已打开该文件，或文件期间发生了变化	如果模型想到这点，就会检查	写入会被拒绝
从招聘信息和电子邮件中粘贴的文本	以“=”开头的文本会变成公式，除非代码加以阻止	始终作为文本写入
之前编辑留下的问题（文本格式的日期、没有状态的行）	你提出要求时才会查找，并通过编写的代码修复	check_tracker 会查找问题，fix_tracker 会在一次经确认的写入中修复
每条回复的时间	只有有人记录下来才知道	每条回复都会记录；reply_times 会显示回复何时停止
邮箱中的回复	模型读取邮件，并判断每封邮件对应哪一行	match_emails 会按相同方式给出行号和修改内容
每项请求	编写、运行并检查脚本	调用一次工具
自由形式的分析、图表、调整表格结构	什么都能做	这不是它的职责：Claude 仍会同时处理这些事
使用位置	Claude 能在你的文件上运行代码的地方，或你上传副本的地方	任何 MCP 客户端：Claude Desktop（普通聊天中）、Claude Code、Cursor、……；也可以通过你自己的服务在浏览器或手机上使用

因此，tracker-mcp 基本上不会赋予 Claude 新能力。它为求职过程中日常处理的事项（记录进展、查看待办、了解哪些方法有效）提供固定规则和安全保障，无需编写说明。Claude 唯一无法事后得知的，是某条回复何时到达，前提是当时没人记录；服务会在回复发生时将其记录下来。

• 规则应写在代码中，而非提示词里。“哪些跟进到期了？”这是需要按照规则进行的日期计算：申请后 10 天，然后每隔 14 天；如果遇到周末就顺延到周一；已关闭的申请不安排跟进。大模型大多数时候都能答对，但每次聊天时都要重新推算，而且出错往往不易察觉：给已被拒绝的申请安排了跟进日期，日期落在周日，或状态名称与下拉菜单中的写法不一致。这里的规则由经过测试的代码实现。静默申请和漏斗也一样。
• 模型无法绕过的安全措施。 你能看到确切的待更改单元格，而且你的确认由服务端验证，不会只听信模型的话。这在没人重读指示的场景下尤其重要：定期的每周审查、漫长的聊天，或从招聘信息中粘贴的、指示模型做某事的备注。
• 步骤更少。 无需编写并运行脚本，只需调用一次工具，答案来得更快，模型也能把注意力集中在你的问题上。
• 随处使用同一份跟踪表。 每次聊天、定期审查以及你使用的每个客户端，都使用同一个文件，而且每项更改都会立即写入其中。

电子表格仍归你所有：你可以继续在 Excel 或 Sheets 中打开它、排序和编辑。代码中没有针对特定跟踪表的内容；服务端会读取你的表头和下拉菜单，并将学到的信息保存在一个小型配置文件中。

如果你只想对申请进行一次性分析，很少更新跟踪表，或者只在浏览器或手机上使用 Claude，且不想运行自己的服务，就不需要 tracker-mcp：Claude 的 Google Sheets 连接器可能就够用了。如果 Claude 已经能按照你编写的指示妥善维护跟踪表，那么你获得的是可靠性，而不是新功能。

快速开始

让 Agent 来处理。 将以下内容粘贴到 Claude Code 或 Codex 中；它会安装所需内容、询问跟踪表的位置、完成连接并检查结果：

Install tracker-mcp for me: an MCP server that lets AI keep my job-application spreadsheet.
Read the instructions for agents and follow them:
https://raw.githubusercontent.com/butyavk/tracker-mcp/main/docs/agent-setup.md
First ask me where my tracker is and which app to connect it to.
Don't edit the tracker yourself, and check at the end that it works.

也可以手动操作。你需要安装 uv，它也会为你下载 Python。选择你的客户端：

Claude Desktop，简便方式： 从最新版本下载 tracker-mcp-<version>.mcpb，双击它，按下 Install，在 Your tracker 中选择跟踪表文件，点击 Save，然后启用扩展程序。在 Mac 上，这种方式还能避免 Documents 文件夹问题。

Claude Desktop，手动方式。 打开 Settings → Developer → Edit Config 并添加：

{
  "mcpServers": {
    "tracker": {
      "command": "uvx",
      "args": ["tracker-mcp"],
      "env": { "TRACKER_PATH": "/Users/you/Documents/job-tracker.xlsx" }
    }
  }
}

在 Windows 上，路径类似于 C:\\Users\\you\\Documents\\job-tracker.xlsx（JSON 中使用双反斜杠）。重启 Claude Desktop。如果 Claude 找不到 uvx，请在 command 中填写其完整路径（which uvx / where uvx）。在 macOS 上，如果跟踪表位于 Documents、Desktop 或 Downloads 文件夹中，请参阅 macOS 隐私设置。

Claude Code： 作为插件安装（包含服务端和 weekly-review 技能；它会询问跟踪表的路径）：

/plugin install tracker-mcp --marketplace butyavk/tracker-mcp

或者只安装服务端：

claude mcp add tracker -e TRACKER_PATH="$HOME/Documents/job-tracker.xlsx" -- uvx tracker-mcp

Cursor、VS Code 和其他客户端： 使用命令为 uvx、参数为 ["tracker-mcp"]、环境变量为 TRACKER_PATH 的 stdio 服务端。Cursor 从 ~/.cursor/mcp.json 读取与 Claude Desktop 相同的 JSON。

从克隆安装（用于修改代码，或在发布版本推出之前安装）：

git clone https://github.com/butyavk/tracker-mcp && cd tracker-mcp && uv sync

并使用 "command": "uv", "args": ["--directory", "/path/to/tracker-mcp", "run", "tracker-mcp"]。

首次启动

首次启动时，服务会读取你的追踪表，找到工作表和标题行，将标题映射到字段（可识别英文和俄文标题），判断下拉列表中的每种状态代表什么，并在追踪表旁边写入 job-tracker.tracker-mcp.toml。它不会修改追踪表本身。让 Claude 描述你的追踪表：它会展示映射关系和值得检查的推测。你可以随时编辑配置；更改会在下次请求时生效，无需重启。

如要在写入任何内容之前查看推测，请自行运行：

uvx tracker-mcp init ~/Documents/job-tracker.xlsx     # writes the config, lists what to check
uvx tracker-mcp --check --tracker ~/Documents/job-tracker.xlsx   # how the config maps the tracker

还没有追踪表？uvx tracker-mcp new ~/Documents/job-tracker.xlsx 会创建一个空白追踪表，其中包含下拉列表、筛选器、汇总工作表及其配置；添加 --lang ru 可使用俄文标题和状态。

每周例行安排

服务会在收到请求时作出响应；它不会发送提醒。养成以下两个习惯，就能充分发挥它的作用：

• 每周一次，运行 每周回顾 提示词（或者直接询问“回顾我本周的求职情况”）：有哪些事项即将到期、哪些事情没了消息、求职漏斗如何推进，以及下一步计划。如果你的客户端支持运行定时任务，可以将这句话安排在周一早上执行。
• 每次有新进展后，用一句话告诉 Claude：“通过 Y 申请了 X”“X 拒绝了我”“已向 X 发送跟进消息”“周五之前无法跟进 X”。它会找到对应行，展示更改，并在你同意后写入。

追踪表可以存放在哪里

	如何指定路径	备注
Excel (.xlsx)	TRACKER_PATH=/path/tracker.xlsx	保留下拉列表、筛选器和汇总公式，并将它们扩展到新行
CSV	TRACKER_PATH=/path/tracker.csv	支持从 Notion、Huntr、Teal 或 Sheets 导出的文件。保留分隔符、编码（UTF-8 或 Windows-1252）和换行符；状态来自配置
Google Sheets	TRACKER_PATH=https://docs.google.com/spreadsheets/d/<id>/edit	登录一次并选择工作表，见下文

Google 表格

只需登录一次并选择跟踪表；无需在 Google Cloud 中进行任何设置：

uvx tracker-mcp auth google

浏览器会打开 Google 的登录页面，然后打开 Google 的文件选择器。选择包含你申请信息的电子表格。tracker-mcp 会为该表格写入配置，并打印需要添加到客户端的内容：与文件的设置方式相同，将该表格的 URL 设为 TRACKER_PATH。

• **tracker-mcp 可以访问的内容：**仅限你在 Google 文件选择器中选择的文件（或它创建的文件），通过 Google 的 drive.file 权限访问。它无法查看你的其他表格或文件、电子邮件或联系人。以后要使用其他表格，请再次运行此命令并选择该表格。
• **登录信息的存储位置：**在你的电脑上，保存在 ~/.tracker-mcp/google-token.json 中（仅你可读取），更改单元格的备份保存在 ~/.tracker-mcp/backups/ 中。没有 tracker-mcp 服务；程序会直接与 Google 通信。要撤销访问权限，请在 myaccount.google.com/permissions 中移除 tracker-mcp。详情请参阅隐私政策。
• **在 Google 的页面上，**你会登录并看到“继续使用 tracker-mcp”的提示，以及通往其主页和隐私政策的链接。Google 尚未审核此应用的品牌信息，因此不会显示徽标；它请求的访问权限（drive.file）是 Google 允许应用在未经审核的情况下申请的权限之一。
• 这台电脑上没有浏览器（通过 SSH 连接的服务端）：uvx tracker-mcp auth google --no-browser 会打印链接；浏览器仍须能够访问这台电脑上的 127.0.0.1 才能完成登录，因此请转发端口，或在浏览器所在的位置登录后复制 ~/.tracker-mcp/。

改用你自己的 Google 客户端（用于分叉项目、限制外部应用的公司账号，或你不希望依赖本项目客户端的情况）：在 Google Cloud 控制台中创建项目，启用Google Sheets API（使用 --pick 时还需启用 Google Picker API），配置同意屏幕（External），创建类型为 Desktop app 的 OAuth 客户端并下载其 JSON：

uvx tracker-mcp auth google --client-secret ~/Downloads/client_secret_….json --pick   # only the sheets you pick
uvx tracker-mcp auth google --client-secret ~/Downloads/client_secret_….json          # all your spreadsheets

不使用 --pick 时，权限（spreadsheets）涵盖你可以打开的所有电子表格，但服务只会打开 TRACKER_PATH 中指定的表格；然后运行 uvx tracker-mcp init "https://docs.google.com/spreadsheets/d/<id>/edit" 写入配置。同意屏幕处于 Testing 状态时，Google 会在 7 天后终止登录；将其发布（Audience → Publish app）即可保持登录。

**或者使用服务账号：**创建服务账号，下载其密钥，将表格共享给该服务账号的电子邮件地址，并在服务的环境中设置 GOOGLE_APPLICATION_CREDENTIALS=/path/key.json。这样，服务便只能访问你共享给它的表格。

远程服务：在网页和手机上使用 Claude

以上内容都在你的电脑上运行，因此 Claude 只能从这台电脑访问跟踪表。tracker-mcp remote 会通过你运行的服务器，以 HTTP 提供相同的工具，适用于 Google Sheets 跟踪表：将其作为自定义连接器添加到 Claude（Settings → Connectors → Add custom connector → https://<your server>/mcp），即可在网页、桌面应用和手机上的 Claude 中使用。多人可以共用一台服务器；每个人分别使用 Google 登录，并操作自己的表格。

登录流程如下：

1. Claude 向服务器注册（OAuth 动态客户端注册），并打开服务器的登录页面。
2. 服务器将你转到 Google：授权你的电子邮件地址和 drive.file（你选择的文件）。
3. 服务器会将你的电子邮件地址与其允许名单进行核对。
4. 同意页面会说明哪个应用正在连接、以谁的身份连接，以及将连接到哪个表格。你可以在 Google 文件选择器中选择跟踪表、新建跟踪表，或继续使用上次选择的表格。
5. Claude 获取服务器自己的令牌（有效期为一小时，可刷新 30 天，每次使用后都会轮换），而不是你的 Google 令牌；后者由服务器加密保存。

写入操作与在你的电脑上一样：预览、由你确认、备份、撤销。在 claude.ai 中，请用明确说明变更内容的“是”来确认预览（例如“是，第 12 行：状态 → 面试”）：自身的安全措施可能会拒绝只回复一个“是”而批准的写入。服务器会按用户分别保存备份和审计日志。远程不可用的功能： export_followups_calendar（没有文件可交给你；请使用日历提示词），以及 Excel 或 CSV 文件。

运行服务器：在 Google Cloud Run 上，从 Cloud Shell 开始：

git clone https://github.com/butyavk/tracker-mcp && cd tracker-mcp
./deploy/cloudrun.sh --project <project-id> --dry-run     # prints the addresses to register
./deploy/cloudrun.sh --project <project-id> --client-id <web client id> \
    --allow [email protected],[email protected]

运行前，请在项目中启用结算；创建类型为 Web application 的 OAuth 客户端，并设置试运行输出的重定向 URI 和 JavaScript 来源，然后在其 Data Access 范围中，除了 drive.file，还添加 openid 和 email。脚本会为服务器数据创建一个私有 Cloud Storage 存储桶，在 Secret Manager 中创建加密密钥，创建文件选择器的 API 密钥（仅限 Picker API，且仅允许你的服务器地址；或通过 --picker-key 传入自己的密钥），在不显示客户端密钥的情况下提示你输入该密钥，并部署一个实例。个人使用时可享受 Cloud Run 的免费额度；存储桶费用仅需几分钱。

客户端只能使用 Claude 连接器回调地址（位于 claude.ai 或 claude.com）或你自己机器上的地址进行注册，以供 MCP Inspector 使用；TRACKER_MCP_REDIRECT_URIS 可更改此列表。 其他主机：可通过 Dockerfile 运行 tracker-mcp remote；设置说明见 tracker-mcp remote --help。任何运行服务器的人都能访问登录该服务器的用户的表格，因此请使用由你信任的人运行的服务器。

Claude 可以用它做什么

工具	类型	功能
describe_tracker	读取	跟踪表的布局：字段 → 列、允许的状态和已关闭状态、后续跟进规则
list_applications	读取	按状态、公司／职位文本、提交日期筛选
get_application	读取	获取某项申请的所有列（按文本或行号）
followups_due	读取	查看 N 天内到期的后续跟进，逾期项优先；以及已提交但没有后续跟进日期的行
stale_applications	读取	查看仍在等待、距离上次联系已静默 N 天以上的申请（上次联系时间为提交日期或最新的、带日期的后续跟进日志条目），且未计划后续跟进
summary	读取	按状态和月份统计数量；统计某个日期范围内的申请批次
funnel	读取	提交 → 已回复 → 筛选 → 面试 → 录用，按总计以及渠道、来源、月份或任意列统计
check_tracker	读取	检查手动编辑留下的问题：日期仍为文本、缺少状态的行、不在下拉列表中的状态、周末安排的后续跟进、已关闭但仍计划后续跟进的行、进度阶段落后于状态的行、未填写日期的回复、重复项
reply_times	读取	统计从提交到首次回复的天数（中位数、第 75 百分位数），按总计和分组查看；以及静默中的申请在 7、14、21、30、45、60 天后仍收到回复的数量
match_emails	读取	判断每封电子邮件对应哪项申请（确认、拒绝、面试、录用），并提供用于记录该信息的写入操作
recent_writes	读取	MCP 服务写入操作的审计日志
add_application	写入	添加状态为未申请的新行；其他列通过 extra 指定；拒绝重复项
mark_applied	写入	记录已提交：日期、渠道、状态，以及按你的规则设置的后续跟进日期
set_status	写入	设置下拉列表中的新状态；已关闭状态会取消待处理的后续跟进；首次回复会填写回复日期（on，默认为今天）
log_followup	写入	记录已发送的后续跟进，并安排下一次跟进或关闭申请
reschedule_followup	写入	在未发送任何内容时（尚未联系、等待额度），更改下一次后续跟进时间，或不再安排后续跟进
edit_application	写入	修正某一行的字段：错误或缺失的日期、拼写错误、进度阶段、自定义列；会检查日期，并将修改原因写入备注
add_column	写入	在最后一列之后添加列，样式与相邻列一致，并在配置中映射该列（replied_on、reached、自定义字段）；撤销操作会同时移除两者
close_stale	写入	一次写入、创建一个备份、完成一步撤销，关闭长期无进展的申请（或指定行）
fix_tracker	写入	一次写入、创建一个备份、完成一步撤销，修复 check_tracker 可修复的问题
calendar_events	读取	将待处理的后续跟进作为全天事件提供，并附带稳定的 ID 行，以便客户端的日历工具可以添加、移动和移除事件，避免重复
export_followups_calendar	文件	在跟踪表旁生成包含待处理后续跟进的 .ics 文件（不会改动跟踪表）
undo_last_write	写入	如果此后没有发生更改，则恢复上一次写入前的状态

对于支持 MCP 提示词的客户端，有四个提示词：每周回顾会检查跟踪表，并逐项查看后续跟进、长期无进展的申请、回复时间、转化漏斗和本周提交的申请，最后制定计划；根据我的电子邮件更新跟踪表会使用客户端自带的邮件工具查找公司的回复，通过 match_emails 匹配并提出更改建议；将我的后续跟进添加到日历会让客户端的日历保持同步（见下文）；起草后续跟进会为某一行写一条简短消息。还有两个资源：tracker://layout 和 tracker://application/{row}。

如果同一家公司在 28 天内已有一项已提交的申请，add_application 和 mark_applied 会发出警告（[rules] same_company_days）；警告会显示在预览中，但不会阻止写入。

回复日期及何时停止等待

为跟踪表添加回复日期列（Replied on、Дата ответа；new 模板中已有此列），set_status 会在首次回复时填写日期：无论是拒绝还是进入任何招聘阶段；对于电子邮件日期，使用 on=。check_tracker 会从 Response 列中为你填入过往日期（其中最早一条与确认收到申请无关的日期），供你审核。之后，reply_times 会显示你在各渠道的回复耗时，以及对方沉默多少天后就不再回复：到了这个时间，关闭申请就不再有任何损失。如果没有此列，它就只会使用通过服务端记录的回复。

在日历中安排后续跟进

tracker-mcp calendar --tracker ~/Documents/job-tracker.xlsx（或 export_followups_calendar 工具）会在跟踪表旁生成一个 .ics 文件，列出尚未完成的后续跟进：每项都是一个全天事件，逾期事项安排在今天，并附上联系人和最后一条日志。打开文件即可将其导入 Calendar、Outlook 或 Google Calendar。这是一个快照：日期变更后，请重新导出并导入（每个事件都会保留其 ID；导入到单独的日历后，就能轻松清除旧副本）。

若要让日历保持同步，请改用 Put my follow-ups in my calendar 提示词，并搭配具有日历工具的客户端（例如使用 Google Calendar 连接器的 Claude）。calendar_events 会在每项后续跟进描述的末尾添加一行 ID；客户端会据此查找已有事件，然后在询问你后添加新事件、移动有变更的事件，并删除申请已关闭的事件。它绝不会更改不含 ID 行的事件。服务端本身不会登录你的日历。

读取工具会标记为只读。覆盖单元格的写入会标记为破坏性操作，所有写入都需要 dry_run、expected_version 和 confirm。

写入如何确保安全

1. 服务端会核实你的确认。 写入前，它会根据跟踪表的当前版本计算计划和确切的单元格变更。支持确认对话框（MCP elicitation）的客户端会在界面中向你展示；否则，写入需要你已查看过的 dry run 令牌，该令牌会记录变更和版本的指纹。写入结果要么与批准的内容完全一致，要么根本不执行。
2. 不会丢失任何人的编辑。 每次读取都会返回一个 version（文件哈希，或工作表值的哈希）；针对旧版本的写入会被拒绝，Excel 打开文件时的写入也会被拒绝。
3. 写入、检查并保留备份。 文件会先写入临时副本，逐个单元格重新读取、备份，然后原子替换；Google Sheet 则会一次性更新有变更的单元格，读取回写结果，并在发现任何差异时回滚。
4. 审计与撤销：每次写入记录一行；只有在此后没有任何变更时才能撤销。
5. 你的数据就是数据：文本不会变成公式，并且会告知模型不要遵循单元格中的指令（例如粘贴的招聘信息）。请参阅 SECURITY.md。

允许使用的状态来自状态列的下拉菜单。系统根据表头文字而非列字母识别列，因此你可以重新排列列的顺序。向 .xlsx 文件添加行时，服务端会将下拉菜单、筛选器和汇总公式扩展到该行。

配置

job-tracker.xlsx 的配置由其旁边的 job-tracker.tracker-mcp.toml 描述（对于 Google Sheet，则为 ~/.tracker-mcp/<id>.tracker-mcp.toml），也可以由 TRACKER_CONFIG 指向的文件描述。运行 uvx tracker-mcp example 会打印一份解释了每个键的配置 （examples/tracker-mcp.example.toml）。简而言之：

sheet = "Applications"

[columns]                 # field = header text (exact, else the first header starting with it)
company = "Company"       # company, role and status are required
role = "Role"
status = "Status"
applied_on = "Applied on"
followup_on = "Follow-up date"
followup_log = "Follow-up log"
salary = "Salary"         # any other key is a custom field

[statuses]
not_applied = "Not applied"
applied = "Applied"
closed = ["Rejected", "Withdrawn", "No response", "Offer"]
rejected = ["Rejected"]

[statuses.stages]         # funnel stages after a reply, in order
screening = ["Screening"]
interview = ["Interview", "Final"]
offer = ["Offer"]

[followups]
first_after_days = 10
next_after_days = 14
weekend_to_monday = true

缺少可选列只会关闭依赖它的功能：如果没有后续跟进列，followups_due 会说明这一点。配置会经过严格验证，因此键拼写错误会报错，而不会静默使用默认值。如果编辑导致配置无效，每个请求都会说明原因，直到问题修复。

漏斗统计会将拒绝计为回复，并且需要知道你的阶段 （[statuses.stages]）。状态列只保存当前状态，因此请添加一个 reached 列（“最远阶段”），以记录最远达到的阶段；否则，面试后被拒绝也只会计为一次回复；set_status 只会向前推进状态，不会回退。 像来源这样的自由文本列，会按第一个括号或破折号之前的文本分组（“Ashby (direct form)” → “Ashby”），也可以按你在 [funnel.groups]（所有列）或 [funnel.by.source]（单列）中列出的子字符串分组。

变量	选项
TRACKER_PATH	--tracker	跟踪表：文件路径或 Google Sheets URL（必填）
TRACKER_CONFIG	--config	配置文件（如果不在跟踪表旁边）
TRACKER_BACKUP_DIR	--backup-dir	备份和 audit.jsonl（默认：跟踪表旁边的 backups-tracker-mcp/；Google Sheet 则为 ~/.tracker-mcp/backups/<id>）
GOOGLE_APPLICATION_CREDENTIALS		Google Sheets 服务账号密钥
TRACKER_MCP_HOME		Google 登录信息和 Sheets 配置的存放位置（默认 ~/.tracker-mcp）

已知限制

• 版本覆盖整个跟踪表，因此其中任何位置的编辑都会使待处理的写入失效。个人使用没有问题；共享跟踪表需要按行记录版本。
• 最后一次版本检查与写入之间仍有一小段时间窗口：.xlsx 文件和 Sheets API 都不支持真正的锁定。
• openpyxl 无法保留较新 Excel 文件中的某些内容，例如从其他工作表获取列表并存储在扩展中的下拉菜单。如果加载文件时警告某部分将被移除，服务会拒绝写入该工作簿，而不是将其删除，并会说明原因。读取不受影响。
• openpyxl 会丢弃公式的缓存值；服务会要求 Excel 在打开时重新计算。
• 在 CSV 文件中，服务写入的文本如果看起来像公式（=、+、@、-1…），就会在前面加上撇号，以便 Excel 将其显示为文本。
• 配置文件以跟踪表的名称命名，不含扩展名，因此同一文件夹中的 jobs.xlsx 和 jobs.csv 会共用一个配置文件；请为其中一个指定 TRACKER_CONFIG。
• 仅支持 .xlsx 和 .csv 文件：保存 .xlsm 文件会丢失其宏，而 .xls、.ods 或 Numbers 文件需要先另存为 .xlsx。
• init 能识别英文和俄文表头及状态词。对于其他语言，它能映射的内容较少，其余内容会列在“check by hand”下。
• 撤销只能回退一步。对于 Google Sheet，它会恢复值，而不会恢复格式。
• 没有对话框时，令牌只能证明已生成预览，且此后没有发生变化；它无法证明模型向你展示了该预览。
• 远程服务将数据保存为文件，并以单个实例运行；它面向个人和少数朋友，而非大量用户。

macOS：Claude Desktop 和你的 Documents 文件夹

简单的方法：使用 Claude Desktop 扩展（来自发布页面的 tracker-mcp-<version>.mcpb）。Claude Desktop 会在自身权限下运行扩展，因此 Documents 中的追踪表可以正常使用：在我们的测试中（Claude Desktop 2.42304，2026 年 10 月），扩展无需任何其他设置就读取了 ~/Documents 中的追踪表。如果 macOS 询问是否允许 Claude 访问该文件夹，请允许。

本节其余内容介绍如何手动将服务添加到 Claude Desktop 的配置中。Claude Desktop 启动此类服务时不会授予它自身的隐私权限。如果你的追踪表位于 Documents、Desktop 或 Downloads 中，服务可能会在日志（Settings → Developer）中报错“Operation not permitted”，而 macOS 不会显示提示。为 Claude 授予完全磁盘访问权限也无法改变这一点。将追踪表移到其他文件夹（例如 ~/JobSearch）是最简单的解决方法。

如需将追踪表保留在原处，sh install.sh /absolute/path/to/tracker.xlsx（在克隆的仓库中运行）会构建一个小型启动器应用 ~/Applications/Tracker MCP.app（macos/launcher.c，约 60 行 C 代码，在本地签名）。它会将服务作为子进程启动，因此 macOS 会询问一次是否允许“Tracker MCP”访问 Documents，并且只有这个应用会获得该权限。该脚本还会运行测试、备份 Claude Desktop 的配置并将服务添加到配置中；请先退出 Claude。

开发

uv sync
uv run pytest                     # the tests use synthetic trackers and a fake Sheets API
uvx ruff check src tests evals
npx @modelcontextprotocol/inspector uv --directory . run tracker-mcp --tracker /path/tracker.xlsx
ANTHROPIC_API_KEY=… uv run python evals/run_evals.py   # does a model use the tools right? (a few cents)

• src/tracker_mcp/tracker.py 是追踪表逻辑；它不涉及 MCP 或存储。
• stores.py 负责读写 .xlsx 和 .csv 文件；gsheets.py 负责 Google Sheets。
• config.py 是配置架构（pydantic，严格）；scaffold.py 实现 init 和 new。
• server.py 包含 MCP 工具、提示词、资源和确认流程。
• evals/ 用于检查模型是否选择了正确的工具、是否在写入前征求确认，以及是否忽略植入单元格中的指令。
• macos/ 是用于 Claude Desktop 的启动器；mcpb/ 用于构建 Claude Desktop 扩展。

有关如何发布，请参阅 CONTRIBUTING.md。使用官方 MCP Python SDK 构建。采用 MIT 许可证。