# Job Tracker MCP Server

A Model Context Protocol (MCP) server for tracking job applications and follow-ups, built with [FastMCP](https://github.com/jlowin/fastmcp) and SQLite. Lets Claude Desktop, Cursor, or any MCP client log applications, move them through the hiring pipeline, schedule follow-up reminders, and check the health of an active job search through natural conversation.

## Features

- Log job applications with company, role, applied date, status, job URL, and notes
- Move applications through a fixed set of pipeline stages, with validation on transitions
- List applications, optionally filtered by status, most recent first
- Schedule follow-up reminders tied to a specific application
- Query pending follow-ups due on or before a given date, so you can ask "what follow-ups do I have this week"
- Mark follow-ups as done
- Get a pipeline summary: counts of applications grouped by status
- The valid pipeline stages exposed as an MCP resource for client discovery

## Tools

| Tool | Description |
|------|-------------|
| `add_application(company, role, date_applied, status, job_url, notes)` | Insert a new job application |
| `update_status(application_id, new_status)` | Move an application to a new pipeline status |
| `list_applications(status)` | List applications, optionally filtered by status, newest first |
| `add_followup(application_id, follow_up_date, note)` | Schedule a follow-up reminder for an application |
| `get_pending_followups(as_of_date)` | List follow-ups due on or before a date that are not yet done |
| `mark_followup_done(followup_id)` | Mark a follow-up as completed |
| `pipeline_summary()` | Count applications grouped by pipeline status |

All dates use `YYYY-MM-DD` format and are validated on input. Valid pipeline stages are: `applied`, `phone_screen`, `technical_interview`, `onsite`, `offer`, `rejected`, `withdrawn`. Passing any other value to `status` or `new_status` raises a clear error.

## Resources

- `pipeline://stages`: JSON array of the ordered pipeline stages, so a client can discover valid status values without guessing.

## Setup

Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).

```bash
uv sync
```

### Claude Desktop config

```json
{
  "mcpServers": {
    "job-tracker": {
      "command": "/path/to/job-tracker-mcp-server/run.sh"
    }
  }
}
```

Replace `/path/to/job-tracker-mcp-server` with the absolute path to this repo.

## Storage

Data is stored in a local SQLite database (`applications.db`, created automatically on first run, gitignored). Override the location with the `JOB_TRACKER_DB_PATH` environment variable.

## Testing

```bash
uv run pytest
```

## License

MIT