Skip to main content
Glama
edwardyun12

job-tracker-mcp

by edwardyun12
OverviewSchemaRelated ServersScoreDiscussions
TypeScript

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.

Related MCP server: Notion MCP Server

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

Tool

What it does

add_application

Records a new application (company, position, optional deadline/status/notes). Applied date is set automatically.

list_applications

Lists tracked applications, optionally filtered by status and/or a deadlineBefore cutoff.

update_status

Finds an application by company name and updates its status. If the name matches more than one application, it lists them and updates nothing rather than guessing which one you meant.

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

Setup

1. Create a Notion integration

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:

Property

Type

Company

Title

Position

Text

Applied Date

Date

Deadline

Date

Status

Select (options: Applied, Screening, Interview Scheduled, Awaiting Result, Offer, Rejected, Withdrawn)

Notes

Text

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.

Available Tools

3 tools
add_applicationAdd job applicationA

Records a new job application in the tracker. Applied date is set to today automatically.

ParametersJSON Schema
NameRequiredDescriptionDefault
notesNoAny extra notes
statusNoInitial status, defaults to "Applied"
companyYesCompany name
deadlineNoApplication deadline, ISO date (YYYY-MM-DD)
positionYesJob title / position

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behaviors. It adds one behavioral detail (auto-set applied date) but omits others like idempotency, return value, or authentication needs. This is minimally adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with minimal fluff. The main action is front-loaded, and the second sentence adds a specific behavioral detail. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is adequate for a simple creation tool with rich schema, but it does not explain success behavior, required fields, or error handling. Given no output schema and no annotations, a bit more context would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all parameters have descriptions. The description adds no extra meaning beyond the schema; it does not discuss parameters at all. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verb 'Records' and resource 'job application', and the title further clarifies purpose. It clearly distinguishes from sibling tools which are listings and updates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use or when alternatives like update_status might be better. The description only states what it does, leaving the agent to infer context from tool names.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_applicationsList job applicationsA

Lists tracked job applications, optionally filtered by status and/or a deadline cutoff.

ParametersJSON Schema
NameRequiredDescriptionDefault
statusNoOnly return applications with this status
deadlineBeforeNoOnly return applications with a deadline before this ISO date (YYYY-MM-DD)

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. The description only states 'lists' without disclosing whether it is read-only, safe, or any rate limits. For a simple list tool, this is minimally acceptable but lacks behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, perfectly front-loaded with verb and resource. No extraneous words. Every part is necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (two optional parameters, no output schema), the description is adequate. It could mention return format or ordering, but for a listing tool it covers the essential functionality.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and each parameter is described in the schema. The description adds no additional meaning beyond what the schema already provides, meeting baseline expectations.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states verb 'lists' and resource 'tracked job applications', and explicitly mentions optional filters by status and deadline. Distinguishes from sibling tools add_application and update_status by being a read-only listing tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. The context implies use for viewing applications, but no exclusions or when-not-to-use advice is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_statusUpdate application statusA

Updates a tracked application's status by company name. If multiple applications match the company, none are updated and the matches are listed for disambiguation.

ParametersJSON Schema
NameRequiredDescriptionDefault
statusYesNew status to set
companyYesCompany name to search for

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, description discloses important disambiguation behavior when multiple matches. Lacks details on return value or side effects (e.g., whether update is reversible), but key behavioral trait is covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words, front-loaded with verb and object.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple update tool with 2 parameters and no output schema, description is fairly complete, explaining behavior with multiple matches. Could mention behavior when no match found.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for both parameters. Description adds context about disambiguation but does not enhance parameter semantics beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it updates an application status by company name and describes disambiguation behavior. Distinguishes from siblings add_application (adds) and list_applications (lists).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides guidance on handling multiple matches by listing them for disambiguation, implying when to use. Could explicitly state prerequisites (e.g., application must exist) or when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0
Disambiguation5/5

Each tool targets a distinct operation: adding, listing, and updating applications. No overlap in purpose.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern with snake_case: add_application, list_applications, update_status.

Tool Count4/5

Three tools cover core workflows for a job tracker, though a delete or archive tool might be expected. Count is well-scoped for the domain.

Completeness4/5

Covers create, read, and update operations, but lacks a delete or archive function, which is a minor gap for full lifecycle management.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/edwardyun12/job-tracker-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server