tracker-mcp

An MCP server for the spreadsheet where you track your job applications: Excel, CSV or Google Sheets. Connect it to Claude (or any MCP client), and the assistant keeps the tracker for you: it answers from it, reminds you what is due, and records what happened, with your yes for every change.

По-русски: как подключить.

You: Which follow-ups are due this week?

Claude: Three. Acme (applied 17 Sep): nudge Sarah Kim on LinkedIn, overdue by two days. Globex: due Thursday, no contact yet. Initech: due Friday.

You: I can't reach anyone at Globex until Monday. Move it.

Claude: Row 8 · Globex — Head of Engineering. Follow-up date: 23 Oct → 27 Oct; follow-up log: + "follow-up moved to 2026-10-27: no contact yet". Write it?

You: Yes.

Claude: Done. A backup was taken first; say "undo" to revert.

Also: "Which channel gets me the most replies?", "Initech rejected me", "I applied to Hooli via a referral today", "close everything that hasn't answered in 45 days".

Why a server? Can't Claude just do this?

It can, if you set it up. Claude reads a spreadsheet you attach, and with access to your files (Claude Code, or Claude working in a folder on your computer) it can edit the tracker by writing a little code, and in claude.ai the Google Sheets connector lets it edit a Google Sheet directly. Give it good instructions (where the tracker is, what each column means, how follow-ups are counted, "back up and ask me before every write") and it works: tracker-mcp grew out of exactly that setup. The difference is where the rules live: in instructions the model reads and follows, or in a program that applies them.

So tracker-mcp mostly does not give Claude new abilities. It gives the everyday part of a job search (record what happened, see what is due, see what works) fixed rules and fixed safety, with no instructions to write. The one thing Claude cannot do later is know when a reply came if nobody wrote it down; the server writes it down as it happens.

• Rules belong in code, not in a prompt. "Which follow-ups are due?" is date arithmetic with your rule: 10 days after applying, then every 14, weekends moved to Monday, nothing for closed applications. A model gets it right most of the time, but it works it out anew in each chat, and the slips are the quiet kind: a follow-up for a rejected application, a date on a Sunday, a status spelled differently from your dropdown. Here the rule is code covered by tests. The same goes for silent applications and the funnel.
• Safety the model cannot skip. You see the exact cells that will change, and your yes is checked by the server, not taken on the model's word. That matters most where no one re-reads the instructions: a scheduled weekly review, a long chat, a note pasted from a job post that tells the model to do something.
• Fewer steps. One tool call instead of writing and running a script, so answers come quicker and the model's attention stays on your question.
• The same tracker everywhere. Every chat, a scheduled review and every client you use work on the same file, and each change lands in it right away.

Your spreadsheet stays yours: you keep opening it in Excel or Sheets, sorting and editing it. Nothing about a particular tracker is in the code; the server reads your headers and dropdowns and keeps what it learned in a small config file.

You don't need tracker-mcp if you only want a one-time analysis of your applications, if you rarely update the tracker, or if you only use Claude in a browser or on your phone and don't want to run a server of your own: Claude's Google Sheets connector may be enough. If Claude already keeps your tracker well with instructions you wrote, what you gain is reliability, not new features.

Quick start

Let an agent do it. Paste this into Claude Code or Codex; it installs what is needed, asks where your tracker is, connects it and checks the result:

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.

Or by hand. You need uv, which also fetches Python for you. Pick your client:

Claude Desktop, the easy way: download tracker-mcp-<version>.mcpb from the latest release, double-click it, press Install, choose your tracker file in Your tracker, Save, and switch the extension on. On a Mac this also avoids the Documents folder problem.

Claude Desktop, by hand. Open Settings → Developer → Edit Config and add:

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

On Windows the path looks like C:\\Users\\you\\Documents\\job-tracker.xlsx (double backslashes in JSON). Restart Claude Desktop. If Claude can't find uvx, put its full path in command (which uvx / where uvx). On macOS, if your tracker is in Documents, Desktop or Downloads, see macOS privacy.

Claude Code: as a plugin (the server plus a weekly-review skill; it asks for the path to your tracker):

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

or just the server:

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

Cursor, VS Code, others: a stdio server with command uvx, arguments ["tracker-mcp"] and the environment variable TRACKER_PATH. Cursor reads the same JSON as Claude Desktop from ~/.cursor/mcp.json.

From a clone (to change the code, or before a release is out):

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

and use "command": "uv", "args": ["--directory", "/path/to/tracker-mcp", "run", "tracker-mcp"].

First start

On its first start the server reads your tracker, finds the sheet and the header row, maps headers to fields (English and Russian headers are understood), works out what each status in your dropdown means, and writes job-tracker.tracker-mcp.toml next to the tracker. It does not touch the tracker itself. Ask Claude to describe your tracker: it shows the mapping and the guesses worth checking. Edit the config whenever you like; changes apply on the next request, no restart needed.

To see the guess before anything is written, run it yourself:

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

No tracker yet? uvx tracker-mcp new ~/Documents/job-tracker.xlsx creates an empty one with dropdowns, a filter, a summary sheet and its config.

A weekly routine

The server answers when asked; it does not send reminders. Two habits make it pay off:

• Once a week, run the Weekly review prompt (or just ask "review my job search for this week"): what is due, what went silent, how the funnel moves, and a plan. If your client can run scheduled tasks, schedule that sentence for Monday morning.
• After each event, tell Claude in a sentence: "applied to X via Y", "X rejected me", "sent the follow-up to X", "can't follow up with X until Friday". It finds the row, shows the change and writes it when you say yes.

Where your tracker can live

Google Sheets

Sign in once and pick your tracker; there is nothing to set up in Google Cloud:

uvx tracker-mcp auth google

Your browser opens Google's sign-in and then Google's file picker. Choose the spreadsheet with your applications. tracker-mcp writes its config for that sheet and prints what to add to your client: the same setup as for a file, with the sheet's URL as TRACKER_PATH.

• What tracker-mcp can reach: only the files you pick in Google's picker (or that it creates), through Google's drive.file permission. It cannot see your other sheets or files, your e-mail or your contacts. To use another sheet later, run the command again and pick it.
• Where the sign-in is kept: on your computer, in ~/.tracker-mcp/google-token.json (readable by you only), with backups of changed cells in ~/.tracker-mcp/backups/. There is no tracker-mcp server; the program talks to Google directly. To withdraw access, remove tracker-mcp at myaccount.google.com/permissions. The privacy policy has the details.
• On Google's screens you sign in "to continue to tracker-mcp", with links to its home page and privacy policy. Google has not reviewed the app's brand, so it shows no logo; the access it asks for (drive.file) is one Google lets apps request without a review.
• No browser on that computer (a server over SSH): uvx tracker-mcp auth google --no-browser prints the link; the browser must still reach 127.0.0.1 on that computer to finish, so forward the port or sign in where the browser is and copy ~/.tracker-mcp/.

Your own Google client instead (a fork, a company account that blocks outside apps, or if you prefer not to rely on this project's client): in the Google Cloud console, create a project, enable the Google Sheets API (and the Google Picker API for --pick), configure the consent screen (External), create an OAuth client of type Desktop app and download its 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

Without --pick the permission (spreadsheets) covers every spreadsheet you can open, although the server opens only the one in TRACKER_PATH; then run uvx tracker-mcp init "https://docs.google.com/spreadsheets/d/<id>/edit" to write the config. While your consent screen is in Testing, Google ends the sign-in after 7 days; publish it (Audience → Publish app) to keep it.

Or a service account: create one, download its key, share your sheet with the service account's e-mail, and set GOOGLE_APPLICATION_CREDENTIALS=/path/key.json in the server's environment. The server can then reach only the sheets you share with it.

Remote server: Claude on the web and on your phone

Everything above runs on your computer, so Claude reaches the tracker only from that computer. tracker-mcp remote serves the same tools over HTTP from a server you run, for Google Sheets trackers: add it to Claude as a custom connector (Settings → Connectors → Add custom connector → https://<your server>/mcp) and it works in Claude on the web, the desktop app and the phone. Several people can use one server; each signs in with Google and works on their own sheet.

How the sign-in goes:

1. Claude registers with the server (OAuth dynamic client registration) and opens its sign-in page.
2. The server sends you to Google: your e-mail and drive.file, the files you pick.
3. The server checks your e-mail against its allow-list.
4. A consent page says which app is connecting, as whom and to which sheet. Pick your tracker in Google's file picker, start a new one, or continue with the sheet you chose last time.
5. Claude gets the server's own tokens (an hour, refreshed for 30 days, rotated on every use), never your Google token, which the server keeps encrypted.

Writes work as on your computer: preview, your yes, a backup, undo. In claude.ai answer the preview with a yes that names the change ("yes, row 12: status → Interview"): its own safeguards may refuse a write approved with a bare "yes". The server keeps the backups and the audit log per person. Not available remotely: export_followups_calendar (no files to hand you; use the calendar prompt) and Excel or CSV files.

Running one on Google Cloud Run, from 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 you@gmail.com,friend@gmail.com

Before that, in the project: billing on; an OAuth client of type Web application with the redirect URI and JavaScript origin the dry run prints, and openid and email added to its Data Access scopes next to drive.file. The script creates a private Cloud Storage bucket for the server's data, an encryption key in Secret Manager, the file picker's API key (Picker API only, your server's address only; or pass yours with --picker-key), asks for the client's secret without showing it, and deploys one instance. At personal use it fits Cloud Run's free tier; the bucket costs cents.

Clients may register only with Claude's connector callback (on claude.ai or claude.com) or an address on your own machine, for the MCP Inspector; TRACKER_MCP_REDIRECT_URIS changes the list. Other hosts: the Dockerfile runs tracker-mcp remote; the settings are in tracker-mcp remote --help. Whoever runs a server can reach the sheets of the people who sign in to it, so use one run by someone you trust.

What Claude can do with it

Four prompts, for clients that show MCP prompts: Weekly review checks the tracker and goes through follow-ups, stale applications, reply times, the funnel and this week's submissions, and ends with a plan; Update the tracker from my e-mail has the client's own mail tool find replies from companies, matches them with match_emails and proposes the changes; Put my follow-ups in my calendar keeps the client's calendar in step (below); Draft a follow-up writes a short message for one row. Two resources: tracker://layout and tracker://application/{row}.

add_application and mark_applied warn when the same company already has an application submitted within 28 days ([rules] same_company_days); the warning shows in the preview and does not stop the write.

Reply dates and when to stop waiting

Give the tracker a reply-date column (Replied on, Дата ответа; the new template has one) and set_status fills it on the first reply: a rejection or any funnel stage, with on= for the e-mail's date. check_tracker fills past ones from the Response column (the earliest date there that is not about the application being received) for you to approve. Then reply_times says how long your replies take per channel, and after how many silent days they stopped coming: the point where closing an application costs nothing. Without the column, it uses only the replies recorded through the server.

Follow-ups in your calendar

tracker-mcp calendar --tracker ~/Documents/job-tracker.xlsx (or the export_followups_calendar tool) writes the open follow-ups as an .ics file next to the tracker: one all-day event each, overdue ones on today, with the contact and the last log line. Open the file to import it into Calendar, Outlook or Google Calendar. It is a snapshot: after the dates change, export and import again (each event keeps its ID; importing into a calendar of its own makes an old copy easy to clear).

To keep a calendar in step instead, use the Put my follow-ups in my calendar prompt with a client that has a calendar tool (Claude with the Google Calendar connector, say). calendar_events gives each follow-up an id line at the end of its description; the client finds the events already there by it, then adds the new ones, moves the changed ones and deletes those whose application closed, after asking you. It never touches events without an id line. The server itself does not sign in to your calendar.

Read tools are marked read-only. Writes are marked destructive where they overwrite cells, and all of them take dry_run, expected_version and confirm.

How a write stays safe

1. The server checks your yes. Before a write it computes the plan, the exact cell changes at the current version of the tracker. A client with confirmation dialogs (MCP elicitation) shows it to you there; otherwise the write needs the token of a dry run that you saw, which fingerprints the changes and the version. The write lands exactly as approved, or not at all.
2. Nobody's edit is lost. Each read returns a version (a hash of the file, or of the sheet's values); a write against an old version is refused, and so is a write while Excel has the file open.
3. Write, check, keep a backup. Files are written to a temporary copy, re-read cell by cell, backed up and swapped in atomically; a Google Sheet gets one update of the changed cells, is read back and rolled back on any difference.
4. Audit and undo: one line per write; undo only if nothing changed since.
5. Your data is data: text never turns into a formula, and the model is told not to follow instructions found in cells (a pasted job post). See SECURITY.md.

Allowed statuses come from the status column's dropdown. Columns are found by header text, not by letter, so you can reorder them. When a row is added to an .xlsx file, the server stretches dropdowns, the filter and summary formulas to it.

Config

job-tracker.xlsx is described by job-tracker.tracker-mcp.toml next to it (for a Google Sheet, ~/.tracker-mcp/<id>.tracker-mcp.toml), or by the file TRACKER_CONFIG points to. uvx tracker-mcp example prints a config with every key explained (examples/tracker-mcp.example.toml). In short:

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

A missing optional column only switches off what needs it: with no follow-up column, followups_due says so. The config is validated strictly, so a typo in a key is an error, not a silent default. If an edit breaks the config, every request says why until it is fixed.

The funnel counts a rejection as a reply and needs to know your stages ([statuses.stages]). The status column only holds the current state, so add a reached column ("Furthest stage") for the furthest stage, or a rejection after an interview counts as just a reply; set_status moves it forward, never back. Free-text columns such as the source are grouped by their text up to the first bracket or dash ("Ashby (direct form)" → "Ashby"), or by substrings you list in [funnel.groups] (all columns) or [funnel.by.source] (one column).

Known limits

• The version covers the whole tracker, so any edit elsewhere in it invalidates a pending write. Fine for one person; a shared tracker would need row-level versions.
• A small window remains between the last version check and the write: neither an .xlsx file nor the Sheets API offers real locking.
• openpyxl cannot keep some parts of newer Excel files, such as dropdowns that take their list from another sheet and are stored in an extension. If loading the file warns that a part would be removed, the server refuses writes to that workbook rather than drop it, and says so. Reading works.
• openpyxl drops cached formula values; the server asks Excel to recalculate on open.
• In a CSV file, text the server writes that starts like a formula (=, +, @, -1…) gets a leading apostrophe, so Excel shows it as text.
• The config is named after the tracker without its extension, so jobs.xlsx and jobs.csv in one folder would share one; give one of them TRACKER_CONFIG.
• Only .xlsx and .csv files: an .xlsm would lose its macros on save, and .xls, .ods or Numbers files need saving as .xlsx first.
• init understands English and Russian headers and status words. In other languages it maps less and lists the rest under "check by hand".
• Undo goes back one step only. For a Google Sheet it restores values, not formatting.
• Without a dialog, the token proves that a preview was made and nothing drifted since. It cannot prove the model showed you that preview.
• The remote server keeps its data as files and runs as one instance; it is meant for a person and a few friends, not for a crowd.

macOS: Claude Desktop and your Documents folder

The easy way: use the Claude Desktop extension (tracker-mcp-<version>.mcpb from the releases). Claude Desktop runs an extension under its own permissions, so a tracker in Documents works: in our test (Claude Desktop 2.42304, October 2026) the extension read a tracker in ~/Documents with nothing else to set up. If macOS asks whether Claude may access the folder, allow it.

The rest of this section is about adding the server to Claude Desktop's config by hand. Claude Desktop starts such servers without its own privacy permissions. If your tracker is in Documents, Desktop or Downloads, the server may fail with "Operation not permitted" in its log (Settings → Developer), and macOS never shows a prompt. Full Disk Access for Claude does not change that. Moving the tracker to another folder (say ~/JobSearch) is the simplest fix.

To keep it where it is, sh install.sh /absolute/path/to/tracker.xlsx (from a clone) builds a tiny launcher app, ~/Applications/Tracker MCP.app (macos/launcher.c, about 60 lines of C, signed locally). It starts the server as its child, so macOS asks once whether "Tracker MCP" may access Documents, and only this app gets that permission. The script also runs the tests, backs up Claude Desktop's config and adds the server to it; quit Claude first.

Development

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 is the tracker logic; it knows nothing about MCP or storage.
• stores.py reads and writes .xlsx and .csv files; gsheets.py does Google Sheets.
• config.py is the config schema (pydantic, strict); scaffold.py is init and new.
• server.py holds the MCP tools, prompts, resources and the confirmation flow.
• evals/ checks that a model picks the right tools, asks before writing and ignores instructions planted in a cell.
• macos/ is the launcher for Claude Desktop; mcpb/ builds the Claude Desktop extension.

See CONTRIBUTING.md for how releases are made. Built with the official MCP Python SDK. MIT licensed.