job-tracker-mcp

A personal job-application tracker, exposed as an MCP server so any MCP-aware LLM client (Claude Desktop, Cline, or my own Nexus assistant) can manage it through plain conversation instead of a UI.

"Add a job application for Amazon, Software Engineer Intern, deadline September 1st" → it's in Notion, correctly filed, no clicking required.

▶ See it running, no setup: this server powers the live Nexus demo — open it and ask "list my job applications" or add one; the three tools below are what the assistant is calling behind the scenes.

Why this exists

I'm job-hunting in the UK and wanted a tracker I'd actually keep using — and a real project to learn Model Context Protocol with, beyond just consuming someone else's MCP server. Building the tool layer myself (rather than wiring up Notion's own official MCP server) is the point: it forces you to design the actual interface an LLM gets to reason over, not just proxy a REST API.

How it works

you: "I finished my internship at Vitality, add it as an offer"
        │
        ▼
LLM decides to call add_application(company: "Vitality", position: "...", status: "Offer")
        │
        ▼
this server executes it against the Notion API and returns a plain-text confirmation
        │
        ▼
LLM relays that back to you in natural language

The server itself has zero natural-language understanding — it just declares three tools with typed schemas. The LLM (via whatever client you connect it to) decides when to call which tool and how to fill in the arguments from your sentence. See src/index.ts for the tool registrations and src/notion.ts for the Notion API layer they call into.

Tools

Status values: Applied, Screening, Interview Scheduled, Awaiting Result, Offer, Rejected, Withdrawn.

Setup

1. Create a Notion integration

• Go to notion.so/my-integrations, create an internal integration, copy the token.

2. Share a page with it

Notion integrations can't see anything until a page is explicitly shared with them — this is a hard requirement of Notion's permission model, not something the code can skip. Create any page (e.g. "Job Tracker Data"), then ••• → Connections → select your integration.

3. Create the tracker database

This server doesn't auto-provision the database yet (see Roadmap) — create one manually under the shared page with these properties:

4. Configure

npm install
cp .env.example .env

Fill in .env:

NOTION_API_TOKEN=ntn_...
NOTION_DATA_SOURCE_ID=...    # the database's data source ID — Notion's
                             # 2025-09-03 API splits database ID from data
                             # source ID; this is the one queries run against

5. Build and connect

npm run build

Point any MCP client at dist/index.js. Example for Claude Desktop / Cline config:

{
  "mcpServers": {
    "job-tracker": {
      "command": "node",
      "args": ["--use-system-ca", "/absolute/path/to/job-tracker-mcp/dist/index.js"]
    }
  }
}

--use-system-ca is only needed on networks that TLS-inspect outbound HTTPS (e.g. behind a corporate proxy) — Node's bundled CA store won't trust that network's root cert even though your OS already does.

Or consume it as a dependency. Nexus installs this repo straight from GitHub and spawns the built dist/index.js itself, passing the Notion credentials through to the child process — no separate config file, no manual .env beside it. That path is why the server reads its credentials from the environment first and only falls back to a local .env.

Tech stack

TypeScript, @modelcontextprotocol/sdk (stdio transport), Zod for tool schema validation, Notion API directly (no SDK — see src/notion.ts).

Roadmap

• ensure_tracker_exists tool — have the server create its own Notion database on first use (schema defined in code) instead of the manual step above. Notion's permission model still requires a human to share one page with the integration once; everything past that point should be automatable.

• research_company tool — given a company name, search for and extract basic facts (industry, size, HQ), then generate interview-prep questions tailored to that company's actual interview style (e.g. Amazon's Leadership-Principles-based behavioral questions), reported via MCP's progress notifications so a client can show live step-by-step progress instead of a single opaque "thinking" state.