Job-application tracker

tracker-mcp

求人応募を記録するスプレッドシート（Excel、CSV、Google Sheets）向けの MCP サーバーです。Claude（または任意の MCP クライアント）に接続すると、アシスタントがトラッカーを管理します。トラッカーをもとに質問に答え、期限を知らせ、起きたことを記録します。変更のたびに、あなたの確認を得てから行います。

По-русски: 接続方法。

You: 今週が期限のフォローアップはどれですか？

Claude: 3件あります。Acme（9月17日に応募）：LinkedInでSarah Kimに連絡してください。2日超過しています。Globex：木曜日が期限ですが、まだ連絡していません。Initech：金曜日が期限です。

You: Globexには月曜日まで誰にも連絡できません。日程を変更してください。

Claude: 8行目 · Globex — エンジニアリング責任者。フォローアップ日：10月23日 → 10月27日；フォローアップ記録：+「2026-10-27にフォローアップ日を変更：まだ連絡していない」。書き込みますか？

You: はい。

Claude: 完了しました。先にバックアップを取りました。元に戻すには「undo」と言ってください。

ほかにも、「最も返信をもらえる連絡方法は？」「Initechに不採用と言われました」「今日、紹介経由でHooliに応募しました」「45日間返信がないものをすべて終了にして」。

サーバーを使う理由は？Claudeだけではできませんか？

設定すればできます。Claudeは添付したスプレッドシートを読み取ります。また、ファイルへのアクセス権があれば（Claude Code、またはパソコン上のフォルダー内で作業するClaude）、少しコードを書いてトラッカーを編集できます。claude.aiでは、Google Sheetsコネクターを使ってGoogle Sheetを直接編集できます。適切な指示（トラッカーの場所、各列の意味、フォローアップの数え方、「書き込む前にバックアップを取り、私に確認する」など）を与えれば、問題なく動作します。tracker-mcpも、まさにその設定から生まれました。違いはルールの置き場所です。モデルが読んで従う指示の中に置くか、それを適用するプログラムの中に置くかです。

	あなたの指示を受けたClaude	tracker-mcp
トラッカーを把握する	あなたが書いた指示をもとにするか、チャットのたびに改めて把握します	ヘッダーとドロップダウンから一度だけ学習し、設定に保存します
フォローアップの日付、返信のない応募、ファネル	モデルがその都度コードを書きます	テスト済みのコードに固定ルールがあり、毎回同じ回答になります
書き込む前に確認する	指示にそう書かれていて、モデルがそれに従う場合に行います	サーバーは、あなたが確認していない書き込みを拒否します
バックアップ、元に戻す、変更ログ	モデルが作成した場合に行います	書き込みのたびに行います
新しい行のドロップダウンと数式	その変更のために書かれたコードによります	毎回、新しい行にも引き継ぎます
Excelでファイルが開かれている、またはファイルがその間に変更された	モデルが気づけば確認します	書き込みを拒否します
求人情報やメールから貼り付けたテキスト	コードで防がない限り、「=」で始まるテキストは数式になります	常にテキストとして書き込みます
以前の編集で残った不整合（テキスト形式の日付、ステータスのない行）	聞けば見つかり、そのためのコードで修正します	check_tracker で検出し、fix_tracker で確認後の1回の書き込みで修正します
返信があった日時	誰かが記録した場合にのみ分かります	返信のたびに記録し、reply_times で返信が途絶えた時期を確認できます
メールボックスに届いた返信	モデルが読み取り、どの行に関するものか判断します	match_emails が、毎回同じ方法で対象の行と変更内容を示します
各リクエスト	スクリプトを書き、実行して、確認します	ツールを1回呼び出します
自由形式の分析、グラフ、シートの再構成	何でもできます	対象外です。Claudeは引き続き、これらを並行して行えます
利用場所	Claudeがファイル上でコードを実行できる場所、またはアップロードしたコピー上	任意の MCP クライアント：Claude Desktop（通常のチャット）、Claude Code、Cursor、...。ブラウザーやスマートフォンからは自分のサーバー経由で利用できます

つまり、tracker-mcpは、ほとんどの場合、Claudeに新しい能力を与えるものではありません。求人探しの日常業務（起きたことを記録する、期限を確認する、うまくいっている方法を把握する）に、書き込み用の指示なしで、固定のルールと安全対策を適用します。あとからClaudeにできないことが1つあります。それは、誰も記録していない場合に、返信がいつ届いたかを知ることです。サーバーは返信があった時点で記録します。

• ルールはプロンプトではなく、コードに記述します。「フォローアップが必要なのはどれですか？」という質問は、ルールに沿った日付計算です。応募から10日後、その後は14日ごと、週末に当たる場合は月曜日にずらし、応募が終了している場合は対象外にします。モデルはたいてい正しく処理しますが、チャットのたびに計算し直すため、ミスは気づきにくいものです。不採用になった応募へのフォローアップ、日曜日の日付、ドロップダウンと異なるステータス表記などがその例です。ここでは、ルールはテストでカバーされたコードです。音沙汰のない応募や応募ファネルについても同様です。
• モデルが省略できない安全対策。 変更されるセルを正確に確認でき、承認はモデルの言葉を鵜呑みにするのではなく、サーバーで検証されます。特に重要なのは、週次レビューのスケジュール実行、長いチャット、求人情報から貼り付けたメモにモデルへの指示が含まれている場合など、誰も指示を読み返さない場面です。
• 手順を減らせます。 スクリプトを書いて実行する代わりに、ツールを1回呼び出すだけなので、回答が速くなり、モデルは質問に集中できます。
• どこでも同じトラッカーを使えます。 どのチャットでも、スケジュールされたレビューでも、使用するすべてのクライアントで同じファイルを使い、変更はすぐに反映されます。

スプレッドシートは引き続き自分のものです。Excel や Sheets で開き、並べ替えや編集ができます。特定のトラッカーについての情報はコードに含まれていません。サーバーがヘッダーとドロップダウンを読み取り、学習した内容を小さな設定ファイルに保存します。

応募状況を一度だけ分析したい場合、トラッカーをほとんど更新しない場合、またはブラウザーやスマートフォンで Claude だけを使い、自分のサーバーを実行したくない場合は、tracker-mcp は必要ありません。Claude の Google Sheets コネクターで十分なことがあります。自分で書いた指示で Claude がすでにトラッカーを適切に管理できているなら、得られるのは信頼性であり、新機能ではありません。

クイックスタート

エージェントに設定してもらう。 これを 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 が必要です。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 ではバックスラッシュを2つ使います）。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 は Claude Desktop と同じ JSON を ~/.cursor/mcp.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 を追加してください。

毎週のルーティン

サーバーは質問されたときに応答します。リマインダーを送ることはありません。次の2つの習慣で役立てることができます。

• 週に一度、Weekly review プロンプトを実行するか、「今週の就職活動を振り返って」と尋ねます。期限が来ているもの、進展が止まったもの、応募状況の推移、そして計画を確認できます。クライアントがスケジュールタスクを実行できる場合は、その文を月曜の朝に実行するよう設定してください。
• 何かあったらその都度、Claude に「X に Y 経由で応募した」「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 Sheets

一度サインインして、トラッカーを選択します。Google Cloud で設定する必要はありません。

uvx tracker-mcp auth google

ブラウザーで Google のサインイン画面が開き、その後 Google のファイル選択画面が開きます。応募先を記録したスプレッドシートを選択してください。tracker-mcp はそのシート用の設定を書き込み、クライアントに追加する内容を表示します。ファイルの場合と同じ設定で、シートの URL を TRACKER_PATH に指定します。

• tracker-mcp がアクセスできる範囲： Google のファイル選択画面で選択したファイル（または tracker-mcp が作成したファイル）のみです。Google の drive.file 権限を通じてアクセスします。他のシートやファイル、メール、連絡先にはアクセスできません。後で別のシートを使う場合は、コマンドをもう一度実行して選択してください。
• サインイン情報の保存場所： お使いのコンピューター上の ~/.tracker-mcp/google-token.json（読み取れるのはご本人のみ）に保存されます。変更したセルのバックアップは ~/.tracker-mcp/backups/ に保存されます。tracker-mcp のサーバーはなく、プログラムは Google と直接通信します。アクセスを取り消すには、myaccount.google.com/permissions で tracker-mcp を削除してください。詳細はプライバシーポリシーをご覧ください。
• Google の画面では、「tracker-mcp に続行するため」のサインインとして表示され、tracker-mcp のホームページとプライバシーポリシーへのリンクが表示されます。このアプリのブランドは Google に審査されていないため、ロゴは表示されません。要求されるアクセス権（drive.file）は、審査なしでアプリがリクエストできるものです。
• そのコンピューターにブラウザーがない場合（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 スプレッドシートのトラッカーの場合は、Claude にカスタムコネクターとして追加してください（Settings → Connectors → Add custom connector → https://<your server>/mcp）。これで、ウェブ版、デスクトップアプリ、スマートフォンの Claude で使えるようになります。1 台のサーバーを複数の人で利用できます。それぞれが Google にサインインし、自分のシートを操作します。

サインインの流れ：

1. Claude がサーバーに登録（OAuth 動的クライアント登録）し、サインインページを開きます。
2. サーバーが Google にリダイレクトします。要求されるのは、メールアドレスと drive.file（選択したファイル）です。
3. サーバーがメールアドレスを許可リストと照合します。
4. 同意ページには、どのアプリが、誰として、どのシートに接続するのかが表示されます。Google のファイル選択画面でトラッカーを選ぶ、新しいトラッカーを作成する、または前回選んだシートを引き続き使う、のいずれかを選びます。
5. Claude が受け取るのは、サーバー独自のトークンです（有効期間は 1 時間、30 日間更新され、使用のたびにローテーションされます）。Google のトークンが渡されることはありません。Google のトークンはサーバー上で暗号化して保管されます。

書き込みの動作はお使いのコンピューター上と同じです。プレビューを確認し、承認すると、バックアップが作成され、元に戻せます。claude.ai では、変更内容を明記してプレビューに対する承認を返してください（「yes, row 12: status → Interview」のように）。「yes」だけで承認した書き込みは、Claude 独自の安全機能により拒否される場合があります。サーバーは、ユーザーごとにバックアップと監査ログを保持します。リモートでは export_followups_calendar（お渡しするファイルがないため。カレンダープロンプトを使用してください）と Excel または CSV ファイルは利用できません。

Cloud Shell から Google Cloud Run で実行する方法：

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 で独自のキーを渡してください）を用意し、クライアントのシークレットを表示せずに入力するよう求めて、インスタンスを 1 つデプロイします。個人利用であれば 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	読み取り	1 件の応募の全列（テキストまたは行番号で指定）
followups_due	読み取り	N 日以内に期限を迎えるフォローアップ（期限超過を先に表示）、フォローアップ日がない応募済みの行
stale_applications	読み取り	まだ返事を待っており、最後の連絡（応募日または日付が記録された最新のフォローアップ）から N 日以上返事がなく、フォローアップの予定もない応募
summary	読み取り	ステータス別・月別の件数、日付範囲で指定したコホート
funnel	読み取り	応募済み → 返信あり → スクリーニング → 面接 → 内定の合計、およびチャネル、流入元、月、任意の列ごとの内訳
check_tracker	読み取り	手動編集で生じた問題：テキストのままの日付、ステータスのない行、ドロップダウンにないステータス、週末のフォローアップ、予定済みフォローアップがある終了行、ステータスに対して最も進んだ段階、日付のない返信、重複
reply_times	読み取り	応募から最初の返信までの日数（中央値、75 パーセンタイル）の合計とグループ別の値、および返信がない状態から 7、14、21、30、45、60 日後に返信を受け取った応募数
match_emails	読み取り	各メール（確認、不採用、面接、内定）の対象となる応募と、それを記録する書き込み内容
recent_writes	読み取り	サーバーによる書き込みの監査ログ
add_application	書き込み	未応募ステータスの新しい行を追加し、その他の列は extra で指定します。重複は拒否します
mark_applied	書き込み	応募済みにします：日付、チャネル、ステータス、ルールに基づくフォローアップ日
set_status	書き込み	ドロップダウンから新しいステータスを設定します。終了ステータスにすると保留中のフォローアップを取り消し、最初の返信時には返信日（on、デフォルトは今日）を入力します
log_followup	書き込み	送信したフォローアップを記録し、次回の予定を設定するか終了します
reschedule_followup	書き込み	何も送信していない場合（まだ連絡していない、クレジット待ちなど）に、次回のフォローアップを変更するか、予定なしにします
edit_application	書き込み	1 行のフィールドを修正します：誤りのある日付や欠落している日付、誤字、最も進んだ段階、カスタム列。日付を検証し、理由をメモに記録します
add_column	書き込み	最後の列の後に、その隣の列と同じ書式の列を追加し、設定で対応付けます（replied_on、reached、独自のフィールドなど）。取り消すと両方が削除されます
close_stale	書き込み	1 回の書き込み、1 つのバックアップ、1 回の取り消し操作で、停滞した応募（または選択した行）を終了します
fix_tracker	書き込み	check_tracker で修正できる問題を、1 回の書き込み、1 つのバックアップ、1 回の取り消し操作で修正します
calendar_events	読み取り	オープン中のフォローアップを、安定した ID 行を含む終日イベントとして返します。これにより、クライアントのカレンダーツールは重複を作成せずに追加、移動、削除できます
export_followups_calendar	ファイル	トラッカーの隣に、オープン中のフォローアップを .ics ファイルとして出力します（トラッカーには変更を加えません）
undo_last_write	書き込み	その後に何も変更されていない場合、最後の書き込み前の状態に戻します

MCP プロンプトを表示するクライアント向けに、4 つのプロンプトがあります：Weekly review はトラッカーを確認し、フォローアップ、停滞した応募、返信までの時間、応募のファネル、今週の応募を順に確認して、最後に計画を作成します。Update the tracker from my e-mail はクライアント独自のメールツールで企業からの返信を探し、match_emails で照合して、変更案を提示します。Put my follow-ups in my calendar はクライアントのカレンダーを同期します（後述）。Draft a follow-up は 1 件の応募に対する短いメッセージを作成します。リソースは 2 つあります：tracker://layout と tracker://application/{row}。

add_application と mark_applied は、同じ会社への応募が 28 日以内にすでに送信されている場合（[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ファイルとしてトラッカーの隣に書き出されます。各フォローアップは終日イベントになり、期限を過ぎたものは今日の日付で登録されます。連絡先と最後のログ行も含まれます。ファイルを開いて、カレンダー、Outlook、Google Calendarにインポートしてください。これはスナップショットです。日付が変わったら、もう一度書き出してインポートしてください（各イベントはIDを保持します。専用のカレンダーにインポートすれば、古いコピーを簡単に削除できます）。

カレンダーを常に最新の状態に保つには、カレンダーツールを備えたクライアント（たとえば、Google Calendarコネクターを使うClaude）でPut my follow-ups in my calendarプロンプトを使います。calendar_eventsは各フォローアップの説明の末尾にID行を付けます。クライアントはそのIDで既存のイベントを特定し、新しいイベントを追加し、変更されたイベントを移動し、応募がクローズされたイベントをあなたに確認してから削除します。ID行のないイベントには決して触れません。サーバー自体がカレンダーにサインインすることはありません。

読み取りツールには読み取り専用と明記されています。書き込みツールはセルを上書きするため破壊的操作と明記されており、すべてdry_run、expected_version、confirmを受け取ります。

書き込みの安全性を保つ仕組み

1. サーバーが承認を確認します。 書き込みの前に、現在のトラッカーのバージョンでの正確なセル変更を含む実行計画を計算します。確認ダイアログ（MCP elicitation）を表示するクライアントでは、その内容を画面に表示します。そうでない場合、書き込みには、確認したドライランのトークンが必要です。このトークンは変更内容とバージョンをフィンガープリント化します。書き込みは承認された内容どおりに反映されるか、まったく反映されないかのどちらかです。
2. 誰かの編集が失われることはありません。 各読み取りではversion（ファイルまたはシートの値のハッシュ）が返されます。古いバージョンに対する書き込みは拒否され、Excelでファイルを開いている間の書き込みも拒否されます。
3. 書き込み、確認、バックアップの保持。 ファイルは一時コピーに書き込まれ、セルごとに再読み込みして確認されたうえでバックアップされ、アトミックに差し替えられます。Google Sheetでは変更したセルを一度に更新し、読み戻して、差異があればロールバックします。
4. 監査と取り消し：書き込みごとに1行記録されます。取り消しは、その後に何も変更されていない場合に限ります。
5. データはデータです：テキストが数式に変わることはありません。また、セル内で見つかった指示（貼り付けられた求人情報など）に従わないよう、モデルに伝えます。SECURITY.mdをご覧ください。

許可されるステータスは、ステータス列のドロップダウンから決まります。列は文字ではなくヘッダーのテキストで特定されるため、並べ替えできます。.xlsxファイルに行を追加すると、サーバーがドロップダウン、フィルター、集計数式をその行まで拡張します。

設定

job-tracker.xlsx は、その隣にある job-tracker.tracker-mcp.toml（Google スプレッドシートの場合は ~/.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]（1 つの列）に記載した部分文字列でグループ化されます。

変数	オプション
TRACKER_PATH	--tracker	トラッカー：ファイルパスまたは Google Sheets の URL（必須）
TRACKER_CONFIG	--config	トラッカーの隣に設定ファイルがない場合に指定する設定ファイル
TRACKER_BACKUP_DIR	--backup-dir	バックアップと audit.jsonl（デフォルト：トラッカーの隣の backups-tracker-mcp/。Google スプレッドシートの場合は ~/.tracker-mcp/backups/<id>）
GOOGLE_APPLICATION_CREDENTIALS		Google Sheets 用のサービスアカウントキー
TRACKER_MCP_HOME		Google のサインイン情報と Sheets の設定ファイルを保存する場所（デフォルトは ~/.tracker-mcp）

既知の制限事項

• バージョンはトラッカー全体を対象とするため、トラッカー内の別の場所を編集すると、保留中の書き込みはすべて無効になります。1 人で使う分には問題ありませんが、共有トラッカーには行単位のバージョン管理が必要です。
• 最後のバージョン確認から書き込みまでの間に、わずかな時間差があります。.xlsx ファイルにも Sheets API にも、実際のロック機能はありません。
• openpyxl は、新しい Excel ファイルの一部を保持できない場合があります。たとえば、別のシートのリストを参照し、拡張機能に保存されたドロップダウンなどです。ファイルの読み込み時に一部が削除されるという警告が表示された場合、サーバーはそのブックへの書き込みを拒否して、データを破棄しないようにします。その場合も読み取りは可能です。
• openpyxl は数式のキャッシュ値を削除します。サーバーは、Excel でファイルを開いたときに再計算するように指定します。
• CSV ファイルでは、サーバーが書き込むテキストが数式のような文字（=、+、@、-1…）で始まる場合、先頭にアポストロフィを付けます。これにより、Excel ではテキストとして表示されます。
• 設定ファイル名は拡張子を除いたトラッカー名に基づくため、同じフォルダーに jobs.xlsx と jobs.csv があると、どちらも同じ設定ファイルを使用します。片方には TRACKER_CONFIG を指定してください。
• 対応ファイル形式は .xlsx と .csv のみです。.xlsm は保存時にマクロが失われます。.xls、.ods、Numbers のファイルは、事前に .xlsx として保存する必要があります。
• init が認識するのは英語とロシア語の見出しおよびステータス用語です。それ以外の言語では認識できる範囲が限られ、残りは「手動で確認」に分類されます。
• 元に戻せるのは 1 つ前の状態までです。Google スプレッドシートの場合、復元されるのは値であり、書式は復元されません。
• ダイアログがない場合、トークンによって証明されるのは、プレビューが作成され、その後に変更がなかったことだけです。モデルにそのプレビューが表示されたことまでは証明できません。
• リモートサーバーはデータをファイルとして保持し、単一のインスタンスとして動作します。大勢ではなく、個人と数人の友人での利用を想定しています。

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 ライセンスです。