tracker-mcp

# tracker-mcp

<!-- mcp-name: io.github.butyavk/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) or the Google Drive
connector it can edit the tracker by writing a little code. 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.

| | Claude with your instructions | tracker-mcp |
|---|---|---|
| Knows your tracker | From the instructions you wrote, or worked out again in each chat | Learned once from your headers and dropdowns, kept in a config |
| Follow-up dates, silent applications, funnel | The model writes code for it each time | Fixed rules in tested code: the same answer every time |
| Asks before writing | When the instructions say so and the model follows them | The server refuses any write you have not confirmed |
| Backup, undo, change log | When the model makes them | Every write |
| Dropdowns and formulas on new rows | Depends on the code written for that change | Extended to new rows, every time |
| Excel has the file open, or it changed meanwhile | Checked if the model thinks of it | The write is refused |
| Text pasted from job posts and e-mails | Text starting with "=" becomes a formula unless the code prevents it | Always written as text |
| What earlier edits left behind (text dates, rows without a status) | Found if you ask, fixed by code written for it | `check_tracker` finds it, `fix_tracker` fixes it in one confirmed write |
| When each reply came | Known only if someone wrote it down | Recorded on every reply; `reply_times` shows when replies stop coming |
| Replies in your mailbox | The model reads them and decides which row each is about | `match_emails` names the row and the change, the same way every time |
| Each request | Write, run and check a script | One tool call |
| Free-form analysis, charts, reshaping the sheet | Anything | Not its job: Claude still does that alongside |
| Where | Where Claude can run code on your files, or on a copy you upload | Any MCP client: Claude Desktop (in a normal chat), Claude Code, Cursor, ...; not in a browser or on a phone |

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
(a server like this runs on your computer). If Claude already keeps your tracker well with
instructions you wrote, what you gain is reliability, not new features.

## Quick start

You need [uv](https://docs.astral.sh/uv/getting-started/installation/), which also
fetches Python for you. Pick your client:

**Claude Desktop, the easy way:** download `tracker-mcp-<version>.mcpb` from the
[latest release](https://github.com/butyavk/tracker-mcp/releases), 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](#macos-claude-desktop-and-your-documents-folder).

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

```json
{
  "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](#macos-claude-desktop-and-your-documents-folder).

**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:

```sh
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):

```sh
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:

```sh
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

| | How to point to it | Notes |
|---|---|---|
| **Excel** (.xlsx) | `TRACKER_PATH=/path/tracker.xlsx` | Dropdowns, filters and summary formulas are kept and extended to new rows |
| **CSV** | `TRACKER_PATH=/path/tracker.csv` | Exports from Notion, Huntr, Teal or Sheets. The delimiter, the encoding (UTF-8 or Windows-1252) and line endings are kept; statuses come from the config |
| **Google Sheets** | `TRACKER_PATH=https://docs.google.com/spreadsheets/d/<id>/edit` | Sign in once and pick the sheet, below |

### Google Sheets

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

```sh
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 (o