mcp server

job-tracker

App to manage job search and application process / status

tim-ireland/job-trackercommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

This project does not publish an install method we can turn into a config. Follow the README instead.

README

synced Oct 22, 2026

Job Search Toolkit

A comprehensive web-based job application tracking system with LaTeX resume generation, built with FastAPI and Docker.

Features

Track Applications: Manage job applications with status tracking, priorities, and deadlines
Resume Generation: Generate customized LaTeX resumes and cover letters for each application
PDF Management: View and download generated PDFs directly from the web interface
Company Tracking: Maintain company information, contacts, and tech stacks
Interview Scheduling: Track interviews with dates, interviewers, and outcomes
Offer Comparison: Compare multiple job offers side-by-side
Activity Export: Export weekly activity reports
Modern UI: Clean, responsive interface with dark/light mode
Docker Support: Containerized application with persistent data volumes
Claude Code MCP Server: Drive your job search from the terminal using natural language via Claude Code

Quick Start

Using Docker (Recommended)

Clone the repository

git clone https://github.com/yourusername/job-search-toolkit.git
cd job-search-toolkit

Create your data directory
```
mkdir ../my-job-search
```
Start the application
```
docker-compose up -d
```
Access the application

Open your browser to http://localhost:8000

The first time you run the application, it will automatically initialize the data directory with example files and structure.

Local Development

If you prefer to run without Docker:

Install dependencies

# Install Python dependencies
pip install -r requirements.txt

# Install LaTeX (Ubuntu/Debian)
sudo apt-get install texlive-latex-base texlive-latex-extra

# Install LaTeX (macOS)
brew install --cask mactex

Set environment variables
```
export DATA_DIR=./data
```
Run the application
```
uvicorn job_tracker.app:app --reload
```

Directory Structure

job-search-toolkit/          # This repository (public)
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── job_tracker/            # Web application
├── templates/              # LaTeX templates
├── scripts/                # Helper scripts
└── docs/                   # Documentation

my-job-search/              # Your data (keep private)
├── applications/           # Job applications
├── source_material/        # Personal resume content
├── custom_templates/       # Custom LaTeX templates
└── job_applications.db     # Database

Usage

Using the Wrapper Script (Recommended)

The job-tracker wrapper script ensures all commands run inside the container:

# Create a new application
./job-tracker create Google "Senior Engineer" developer

# Show customization guidance
./job-tracker customize Google_Senior_Engineer

# Compile resume and cover letter PDFs
./job-tracker compile Google_Senior_Engineer

# Sync applications to database
./job-tracker sync

# Open shell in container
./job-tracker shell

# Get help
./job-tracker help

Optional: Add to your PATH for system-wide access:

echo 'export PATH="$HOME/Development/job-search-toolkit:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Now use from anywhere
job-tracker create Company "Job Title"

Alternative: Shell Aliases

For power users, add these to your ~/.bashrc or ~/.zshrc:

alias jt-create="docker exec -it job-search-tracker scripts/create_application.sh"
alias jt-compile="docker exec -it job-search-tracker scripts/compile_application.sh"
alias jt-sync="docker exec -it job-search-tracker python scripts/sync_applications.py"
alias jt-shell="docker exec -it job-search-tracker bash"

See docs/SHELL_ALIASES.md for more options.

Creating Applications

Applications are stored in your data directory at applications/Company_JobTitle/:

job_description.txt - The job posting
config.txt - Configuration (template type, priority, status)
resume.tex - Generated LaTeX resume
resume.pdf - Compiled PDF
cover_letter.tex - Generated cover letter
cover_letter.pdf - Compiled PDF

Edit the .tex files with your favorite editor, then compile:

./job-tracker compile Company_JobTitle

Syncing Applications

If you create applications manually in the filesystem, sync them to the database:

./job-tracker sync

Configuration

Environment Variables

DATA_DIR - Path to data directory (default: /data in Docker)
DATABASE_URL - Database connection string (default: SQLite in data dir)
TEMPLATES_DIR - Path to LaTeX templates

Docker Compose

You can customize the data path in docker-compose.yml:

volumes:
  - /path/to/your/data:/data

Or set the DATA_PATH environment variable:

DATA_PATH=/path/to/your/data docker-compose up

Templates

The toolkit includes several resume templates:

base_resume.tex - Standard resume format
manager_resume.tex - Management-focused resume
director_resume.tex - Executive-level resume
cover_letter.tex - Cover letter template

Create custom templates in your data directory at custom_templates/.

API Documentation

Once running, view the interactive API documentation at:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

Weekly Activity Export

The toolkit includes specialized endpoints for exporting job search activity

Export Previous Week (Text Format)

curl http://localhost:8000/api/reports/dua-weekly

Export Specific Week (Text Format)

# Week starting Sunday, March 9, 2026
curl http://localhost:8000/api/reports/dua-weekly?week_start=2026-03-09

Export Previous Week (CSV Format)

curl http://localhost:8000/api/reports/dua-weekly-csv -o weekly_report.csv

Export Specific Week (CSV Format)

curl "http://localhost:8000/api/reports/dua-weekly-csv?week_start=2026-03-09" -o weekly_report.csv

Export Date Range (Text Format)

# Get all activity from February 1 through March 31, 2026
curl "http://localhost:8000/api/reports/dua-range?start_date=2026-02-01&end_date=2026-03-31"

Export Date Range (CSV Format)

curl "http://localhost:8000/api/reports/dua-range-csv?start_date=2026-02-01&end_date=2026-03-31" -o range_report.csv

Report Format: Each activity entry includes:

Date: When the activity occurred
Position: Job title
Pay rate: Salary range or "Not specified"
Employer name and address: Company name with website or location
Job ID or person contacted: Application ID or contact person
Contact email, website, or phone: Contact information
Result: Status of the application (Applied, Screening, Interview, Offer Received, Rejected, etc.)

The export captures ALL job search activity that progressed during the week, including:

Applications submitted
Phone screenings received
Interviews conducted
Offers received
Applications closed (rejected/withdrawn/accepted)

Claude Code MCP Server

The toolkit includes a Rust-based MCP (Model Context Protocol) server that lets you manage your job search pipeline directly from Claude Code using natural language.

Quick Setup

The MCP server binary is built into the Docker image automatically. To connect Claude Code to it:

Rebuild the image (if you haven't since the MCP server was added):
```
docker compose build
docker compose up -d
```

Register the server by adding this to ~/.claude/mcp.json:

{
  "mcpServers": {
    "job-tracker": {
      "command": "docker",
      "args": ["exec", "-i", "-e", "JOB_TRACKER_URL=http://localhost:8000",
               "job-search-tracker", "/usr/local/bin/job-tracker-mcp"]
    }
  }
}

Restart Claude Code — the server loads at startup.

Example Usage

Once connected, you can talk to your job search data naturally:

"Show me my pipeline summary"
"Add an application for Stripe, Staff Engineer role, P1 priority"
"Log that I had a call with the Google recruiter today"
"Schedule a technical interview for my Stripe application on Friday at 2pm"
"Which applications are still in Pipeline status?"
"Compare my current offers"

Claude can also prepare tailored application documents end-to-end:

"Create a manager-template application for Figma, Engineering Manager - Observability,
 P2 priority, salary $250k-$350k. Here's the job description: [paste]
 Customize the resume to highlight observability and Datadog experience, then compile it."

This scaffolds the application directory with LaTeX templates, edits resume.tex and cover_letter.tex to match the role, compiles both to PDF, and registers the application in the database — all in one conversation turn.

See docs/MCP_SERVER.md for the full document workflow and all available tools.

Development

Running Tests

pytest

Code Style

black .
flake8

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

License

MIT License - see LICENSE file for details

Privacy

This toolkit is designed to keep your personal job search data separate from the application code. Your data directory should be:

Kept in a separate location
Backed up regularly
Never committed to a public repository
Optionally tracked in a private git repository

Support

Acknowledgments

Built with: