# JobLens MCP

![Python](https://img.shields.io/badge/Python-3.10+-blue?style=for-the-badge&logo=python&logoColor=white)
![MCP](https://img.shields.io/badge/Model%20Context%20Protocol-Claude-orange?style=for-the-badge)
![Adzuna](https://img.shields.io/badge/Adzuna-Jobs%20API-green?style=for-the-badge)
![License](https://img.shields.io/badge/license-MIT-lightgrey?style=for-the-badge)

A Model Context Protocol (MCP) server that gives Claude (or any
MCP-compatible AI assistant) structured, live context about jobs and
careers: search real job postings, parse a resume locally, and score how
well a resume matches a given job — all through **official, ToS-compliant
APIs and local file parsing**. No scraping. No stored platform passwords.
No automated browser logins.

---

## Table of Contents

- [Why This Exists](#why-this-exists)
- [Features](#features)
- [Architecture](#architecture)
- [Installation](#installation)
- [Configure Claude Desktop](#configure-claude-desktop)
- [Example Prompts](#example-prompts)
- [Roadmap](#roadmap)

---

## Why This Exists

Most "LinkedIn scraper" MCP servers automate a real login through Selenium
and scrape profile/job pages — which **violates LinkedIn's Terms of
Service** and puts a user's account at risk of a ban.

JobLens solves the same underlying problem — giving an AI assistant rich
job-market context — using a free, official job-search API and local
resume parsing instead. Same outcome, zero ToS risk.

## Features

| Feature | Description |
|---|---|
| 🔍 **Live Job Search** | Query real job postings (title, company, location, salary, description) via the [Adzuna Jobs API](https://developer.adzuna.com/) |
| 📄 **Resume Parsing** | Extract skills, email, and phone from a local PDF/text resume — entirely on-device |
| 🎯 **Resume-to-Job Match Scoring** | Transparent skill-overlap score (0–100) between a parsed resume and any job description, with matched/missing skills listed |
| ⚡ **Search + Match** | One call searches jobs *and* ranks them by fit to your resume |

## Architecture

```
joblens-mcp/
├── src/joblens_mcp/
│   ├── server.py       # MCP server + tool definitions (FastMCP)
│   ├── jobsource.py    # Adzuna API client (swap for any job-board API)
│   └── resume.py       # Local resume parsing + match scoring
├── main.py              # Entry point
├── pyproject.toml
└── requirements.txt
```

`jobsource.py` is intentionally isolated from `server.py` — swapping
Adzuna for USAJobs, Indeed's Publisher API, RemoteOK, or Jooble means
editing **one file**, not the MCP tool layer.

## Installation

**Prerequisites**
- Python 3.10+
- A free [Adzuna API](https://developer.adzuna.com/) `app_id` and `app_key` (instant signup, no scraping involved)

**1. Clone the repository**
```bash
git clone https://github.com/rohith-jpg/joblens-mcp
cd joblens-mcp
```

**2. Set up environment & install dependencies**

Using `uv` (recommended):
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv
source .venv/bin/activate   # macOS/Linux
uv pip install -e .
```

Or with plain `pip`:
```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

**3. Add your API credentials**
```bash
cp .env.example .env
# then edit .env with your ADZUNA_APP_ID and ADZUNA_APP_KEY
```

**4. Run the server**
```bash
uv run main.py
# or
python main.py
```

## Configure Claude Desktop

Add this to your Claude Desktop config (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "joblens": {
      "command": "/path/to/uv",
      "args": ["--directory", "/path/to/joblens-mcp", "run", "main.py"],
      "env": {
        "ADZUNA_APP_ID": "your_app_id",
        "ADZUNA_APP_KEY": "your_app_key"
      }
    }
  }
}
```

Restart Claude Desktop, then look for the tools (hammer) icon to confirm
JobLens is connected.

## Example Prompts

- *"Search for remote data engineer jobs and tell me which ones best match my resume at `/Users/me/resume.pdf`."*
- *"Parse my resume and tell me what skills I'm missing for a Senior Backend Engineer role."*
- *"What job categories does the search API support for the UK?"*

## Roadmap

- [ ] Additional job-board sources (USAJobs, RemoteOK, Greenhouse public job boards)
- [ ] `cover_letter_draft` tool using match results to draft a tailored cover letter
- [ ] Caching/rate-limit handling for high-volume searches

## License

MIT — see [`LICENSE`](./LICENSE).

## Acknowledgements

Built using the [Model Context Protocol](https://modelcontextprotocol.io)
Python SDK and the [Adzuna Jobs API](https://developer.adzuna.com/).

---

**Note:** This project deliberately avoids any LinkedIn scraping or
automated login. All data sources used are official, public APIs or files
the user provides locally.

<p align="center">Built by <a href="https://github.com/rohith-jpg">Rohith Singhu</a></p>