Job Matcher MCP

🎯 AI-powered job search and resume customization MCP (Model Context Protocol) server

Automate your job search and customize your resume for each role in under a minute. Powered by job APIs and Claude LLM.

---

📋 Table of Contents

• Quick Start (5 minutes)
• Features
• Installation
• Configuration
• Usage
• MCP Tools Reference
• Architecture
• Troubleshooting

---

🚀 Quick Start

Goal: Get the server running with mock data in 5 minutes (no API keys needed).

1. Clone the repository

\\ash cd job-matcher-mcp \\

2. Install dependencies

\\ash pip install -r requirements.txt \\

3. Run with mock data

\\ash export USE_MOCK_DATA=true python mcp_server.py \\

Expected output: \
=== Testing search_jobs === { "success": true, "job_listings": [ { "id": "mock_1", "title": "Senior Product Manager", "company": "TechCorp Inc", "location": "San Francisco, CA", ... } ], ... }

=== Testing customize_resume === { "success": true, "customized_resume": "# John Doe...", ... } `

✅ Success! Your MCP server is working. Now let's add real API keys.

---

✨ Features

Feature	Status	Description
Job Search	✅ MVP	Query 1000s of job listings via Adzuna API
Resume Customization	✅ MVP	AI-powered resume tailoring using Claude
Skill Matching	✅ MVP	Identify matched/missing skills
ATS Optimization	✅ MVP	Automatic keyword injection for ATS
Mock Data Mode	✅ MVP	Test without API keys
Multi-API Support	🔜 v1.2	Add Indeed, LinkedIn, AngelList
Cover Letter Generation	🔜 v1.2	Auto-generate cover letters
Application Tracking	🔜 v2.0	Track applications & interviews

---

🔧 Installation

Prerequisites

• Python 3.10 or higher
• pip (Python package manager)
• Git

Step 1: Clone the repository

\\ash git clone https://github.com/yourusername/job-matcher-mcp.git cd job-matcher-mcp \\

Step 2: Create virtual environment (recommended)

\\ash

macOS/Linux

python3 -m venv venv source venv/bin/activate

Windows

python -m venv venv .\venv\Scripts\Activate.ps1 \\

Step 3: Install dependencies

\\ash pip install -r requirements.txt \\

---

⚙️ Configuration

1. Get API Keys

Adzuna API (Free)

1. Go to https://developer.adzuna.com/
2. Create an account
3. Create an app to get App ID and App Key
4. Free tier: ~100 requests/day

Anthropic Claude API (Paid, .50-5/month)

1. Go to https://console.anthropic.com/
2. Create an account
3. Generate an API key
4. Pricing: ~.003 per 1K input tokens, .015 per 1K output tokens

2. Create .env file

\\ash cp .env.example .env \\

3. Add your API keys to .env

\\env ADZUNA_APP_ID=your_actual_app_id ADZUNA_APP_KEY=your_actual_app_key ANTHROPIC_API_KEY=sk-ant-your_actual_api_key USE_MOCK_DATA=false LOG_LEVEL=INFO \\

4. Load environment variables

\\ash

macOS/Linux

export \

Windows PowerShell

Get-Content .env | ForEach-Object { , \ = .Split('=') if () { Set-Item -Path env:\ -Value \ } } \\

---

💻 Usage

Run the server

\\ash python mcp_server.py \\

Test with curl (example)

\\ash

Search for jobs

curl -X POST http://localhost:8000/tools/search_jobs \ -H "Content-Type: application/json" \ -d '{ "role": "Product Manager", "location": "San Francisco, CA", "experience_years": 5, "max_results": 10 }'

Customize resume

curl -X POST http://localhost:8000/tools/customize_resume \ -H "Content-Type: application/json" \ -d '{ "base_resume": "...", "job_description": "...", "template": "modern" }' \\

Python example

\\python from mcp_server import JobMatcherMCPServer

server = JobMatcherMCPServer()

Search jobs

jobs = server.search_jobs( role="Product Manager", location="San Francisco, CA", experience_years=5, max_results=10 ) print(jobs)

Customize resume

resume = server.customize_resume( base_resume="Your resume text here...", job_description="Job description here...", template="modern" ) print(resume) \\

---

🛠️ MCP Tools Reference

Tool 1: \search_jobs\

Search for job listings based on criteria.

Input Schema

\\json { "role": "Product Manager", // Required: Job title "location": "San Francisco, CA", // Required: Geographic location "experience_years": 5, // Required: Years of experience "max_results": 10, // Optional: Limit results (default: 10) "use_mock_data": false // Optional: Use mock data (default: false) } \\

Output Schema

\\json { "success": true, "job_listings": [ { "id": "12345", "title": "Senior Product Manager", "company": "TechCorp", "location": "San Francisco, CA", "link": "https://...", "salary_min": 120000, "salary_max": 160000, "posted_date": "2026-08-17T10:00:00Z", "description_snippet": "We are looking for..." } ], "total_found": 123, "search_time_ms": 1234, "error": null } \\

Example

\\python jobs = server.search_jobs( role="Product Manager", location="Remote", experience_years=3, max_results=5 ) \\

---

Tool 2: \customize_resume\

Customize resume for a specific job using AI.

Input Schema

\\json { "base_resume": "# Jane Doe...", // Required: Your resume text "job_description": "We are looking for...", // Required: Job posting "template": "modern", // Optional: modern|classic|minimal "use_mock_data": false // Optional: Use mock data } \\

Output Schema

\\json { "success": true, "customized_resume": "# Jane Doe...", "match_analysis": { "skills_match_percentage": 82, "matched_skills": ["Product Management", "Leadership"], "missing_skills": ["Machine Learning", "Cloud"], "suggestions": ["Add ML experience if applicable"], "keywords_added": ["Data-driven", "Cross-functional"] }, "generation_time_ms": 2345, "error": null } \\

Example

\\python customized = server.customize_resume( base_resume=open("resume.txt").read(), job_description=open("job_posting.txt").read(), template="modern" ) \\

---

🏗️ Architecture

┌─────────────────────────────────────────────────────┐ │ User/AI Agent (Chat, Script, API Client) │ └────────────────┬────────────────────────────────────┘ │ MCP Protocol ┌────────────────▼────────────────────────────────────┐ │ Job Matcher MCP Server │ │ ┌──────────────────────────────────────────────┐ │ │ │ Tool: search_jobs() │ │ │ │ - Query Adzuna API │ │ │ │ - Parse & structure results │ │ │ └──────────────────────────────────────────────┘ │ │ ┌──────────────────────────────────────────────┐ │ │ │ Tool: customize_resume() │ │ │ │ - Send to Claude API │ │ │ │ - Parse & return customized resume │ │ │ └──────────────────────────────────────────────┘ │ │ ┌──────────────────────────────────────────────┐ │ │ │ External APIs │ │ │ │ - Adzuna Job Search API │ │ │ │ - Anthropic Claude API │ │ │ └──────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────┘

---

🔍 Troubleshooting

Issue: \ModuleNotFoundError: No module named 'anthropic'\

Solution: Install dependencies \\ash pip install -r requirements.txt \\

Issue: \API request failed: Unauthorized\

Solution: Check your API keys in .env \\ash

Verify keys are set

echo
echo
\\

Issue: \No jobs found\

Solution: Try a different role/location or increase max_results \\python

Try broader search

jobs = server.search_jobs( role="Manager", # More general term location="New York, NY", experience_years=5, max_results=50 ) \\

Issue: \Claude API response too slow\

Solution: Use mock data for testing \\python resume = server.customize_resume( base_resume="...", job_description="...", use_mock_data=True # Skip API call ) \\

Issue: \Rate limit exceeded\

Solution: Adzuna free tier has limits. Implement caching: \\python

Store job search results

cached_jobs = {} key = f"{role}{location}{experience_years}" if key not in cached_jobs: cached_jobs[key] = server.search_jobs(...) \\

---

🚢 Deployment

Deploy to Vercel

\\ash

1. Create Vercel account at https://vercel.com

2. Install Vercel CLI

npm install -g vercel

3. Deploy

vercel

4. Add environment variables in Vercel dashboard

Settings → Environment Variables

\\

Deploy to Railway

\\ash

1. Create Railway account at https://railway.app

2. Connect your Git repository

3. Add environment variables in Railway dashboard

\\

---

📊 Performance Metrics (Target)

Operation	Target Time	Actual
Job search	<5 seconds	~2-3s
Resume customization	<10 seconds	~3-5s
Mock job search	<100ms	~50ms
Mock resume customization	<500ms	~200ms

---

📚 API References

• Adzuna API: https://developer.adzuna.com/docs
• Claude API: https://docs.anthropic.com/
• MCP Protocol: https://modelcontextprotocol.io/

---

📝 License

MIT License - see LICENSE file for details

---

👨‍💼 Author

Built for tech product managers in job transition.

Version: 1.0.0
Last Updated: 2026-08-17
Status: MVP Ready