mcp-job-tracker

An MCP server that lets Claude track your job applications. You tell Claude about an application, and it saves it in a local JSON file on your computer. You can then list your applications, update their status and see which ones need a follow-up. There is no database and no account to set up.

Tools

• add_application saves a new application with the status applied.

• list_applications lists your applications, newest first. If some are hidden by the limit, the last line says how many.

• update_status changes the status of one application.

• followups_due lists applications that are still applied after a number of days, so you know who to follow up with.

The possible statuses are applied, replied, interview, rejected and offer.

Related MCP server: Job Tracker MCP Server

Requirements

• Node.js 20 or newer (required by the MCP TypeScript SDK, @modelcontextprotocol/server)

• npm (installed with Node.js)

• Claude Desktop, or another MCP client that can start a stdio server

Install and build

git clone https://github.com/developermaroof/mcp-job-tracker.git
cd mcp-job-tracker
npm install
npm run build

npm run build runs the TypeScript compiler (tsc) and writes the JavaScript output to build/. Run it again after every change to src/index.ts.

Connect to Claude Desktop

1. In Claude Desktop, open Settings > Developer > Edit Config. This opens claude_desktop_config.json. On Windows the file is at %APPDATA%\Claude\claude_desktop_config.json.

2. Add the server inside mcpServers:

   {
     "mcpServers": {
       "job-tracker": {
         "command": "C:\\Program Files\\nodejs\\node.exe",
         "args": ["C:\\path\\to\\mcp-job-tracker\\build\\index.js"]
       }
     }
   }

   Replace C:\\path\\to\\mcp-job-tracker with the folder where you cloned the project.

3. Fully quit Claude Desktop and open it again. Closing the window is not enough, because Claude Desktop keeps running in the system tray. Right-click the Claude icon in the system tray (bottom right of the taskbar), choose Quit, then start Claude Desktop again.

Notes for Windows:

• Every backslash in the JSON file must be doubled (\\). A single backslash is an escape character in JSON, and the config will not load.

• Use the full path to node.exe, not just node. Claude Desktop does not always see the same PATH as your terminal. To find the path, run where.exe node in a terminal and use the path it prints, with the backslashes doubled.

• If mcpServers already has other servers, put a comma after the closing } of the entry before this one. Do not put a comma after the last entry.

On macOS the config file is at ~/Library/Application Support/Claude/claude_desktop_config.json, and paths use forward slashes, for example /Users/you/mcp-job-tracker/build/index.js.

If the tools do not show up, check the log files in %APPDATA%\Claude\logs on Windows or ~/Library/Logs/Claude on macOS.

Connect to Claude Code

macOS or Linux:

claude mcp add --scope user job-tracker -- node /path/to/mcp-job-tracker/build/index.js

Windows (PowerShell or Command Prompt):

claude mcp add --scope user job-tracker -- node "C:\path\to\mcp-job-tracker\build\index.js"

• --scope user makes the server available in all your projects. Without it, the default scope local adds it to the current project only.

• Everything after -- is the command that starts the server. On the command line, use normal single backslashes. Claude Code writes them correctly into its own config.

• To check it, run claude mcp list. It should show job-tracker as Connected. Inside Claude Code, /mcp shows the server status.

Example prompts

• "Add a job application: Frontend Developer at Acme Corp on LinkedIn, link https://example.com/jobs/123."

• "I applied to Globex for a React Developer role on Upwork on 2026-10-20. Add it."

• "Show my job applications."

• "Show my last 5 applications."

• "Show only the applications where I have an interview."

• "Globex replied to me. Update application 2 to replied."

• "Which applications need a follow-up?"

• "Which applications have had no reply for more than 14 days?"

How it works

• stdio transport. Claude Desktop starts the server as a child process (node build/index.js) and talks to it through standard input and standard output. Each message is a JSON-RPC message on its own line. There is no network port and no web server.

• zod validation. Every tool describes its inputs with a zod schema. The MCP SDK turns these schemas into JSON Schema so Claude knows which inputs each tool takes, and it checks every call against the schema before the tool code runs. Invalid input, such as a missing role, an unknown status or a date in the future, is rejected with an error message and nothing is saved.

• Never use console.log. In a stdio server, stdout is used only for protocol messages. console.log writes to stdout, so any log line would get mixed into the messages, the client would not be able to read them, and the connection can break. Use console.error instead. It writes to stderr, which Claude Desktop saves in its log files.

• Storage. Applications are saved in data/applications.json inside the project folder. The path is worked out from the location of build/index.js, not from the current working directory, because Claude Desktop can start the server from any folder. The data folder and the file are created automatically on the first tool call. Each new application gets the next free ID number. The file is listed in .gitignore, so your job search data is never committed.

Project structure

mcp-job-tracker/
  .github/
    workflows/
      ci.yml            GitHub Actions: build and test on every push and pull request
  skill/
    job-tracker/
      SKILL.md          Agent Skill: tells an AI agent when and how to use the tools
  src/
    index.ts            Server code: storage helpers and the 4 tools
    lib.ts              Pure helpers: date check, follow-up filter, newest-first sorting
    lib.test.ts         Vitest tests for lib.ts (not included in the build)
  build/                Compiled JavaScript, created by npm run build (not in git)
  data/
    applications.json   Your saved applications, created on first use (not in git)
  .gitignore
  LICENSE               MIT license
  package.json          Dependencies and the build and test scripts
  package-lock.json     Exact dependency versions
  tsconfig.json         TypeScript compiler settings
  README.md

Agent Skill

The folder skill/job-tracker/ contains an Agent Skill. Its SKILL.md tells an AI agent when to use the four tools and how, with setup steps and example conversations. The skill only contains instructions, so the MCP server must still be installed and connected as described above.

• Claude Code: copy the job-tracker folder to ~/.claude/skills/ to use it in all projects, or to .claude/skills/ inside one project.

• Claude apps: zip the job-tracker folder and upload it under Customize > Skills. Skills need code execution to be turned on.

Development

npm install
npm run build
npm test

npm test runs the Vitest tests in src/lib.test.ts once. Running the tests needs Node.js 22.12 or newer (required by Vitest). GitHub Actions runs the build and the tests on Node.js 22 and 24 for every push and pull request to main.

License

MIT. See LICENSE.

Built by Maroof Qureshi

developermaroof.com