# naukri-mcp

A local [MCP](https://modelcontextprotocol.io) server for **your own**
Naukri.com account: search jobs, view job details, save/apply to jobs, check
applied jobs, read your profile, and read recruiter messages — from Claude
Desktop (or any MCP-compatible client). Built on
[`patchright`](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright-python) (a
stealth-patched Playwright) driving a real Chromium browser with a
persistent, logged-in profile, so you authenticate once by hand and every
tool call afterward reuses that session headlessly.

**Not affiliated with, endorsed by, or supported by Naukri.com / Info Edge
(India) Ltd.** "Naukri" is a trademark of its respective owner, used here
only to describe interoperability.

## Read this before you install

- **This automates your own Naukri account, under your own login.** It
  doesn't bypass authentication or access anything you couldn't already see
  yourself — it drives a real browser session as you.
- **Naukri's Terms of Service, like most job sites, restrict automated / bot
  access to accounts.** Using this is a judgment call about your own
  account. Keep call volume reasonable — don't loop `search_jobs`, don't
  mass-apply — to avoid tripping anti-bot defenses or a manual account
  review. This project claims no responsibility for actions taken with it;
  you are responsible for how you use it and for complying with Naukri's
  terms.
- **This never sees or handles your password.** `naukri_login` opens a real,
  visible Chrome window and you log in (including any OTP) yourself; the
  tool only watches for the session cookie that appears afterward.
- **Selectors will drift.** Naukri redesigns its markup periodically, like
  any large site. `extract.py` tries a few known selector variants and falls
  back to raw page text rather than crashing, but expect the occasional PR
  to fix a broken selector after a Naukri redesign. Confirmed working
  end-to-end (login + `get_my_profile`) as of the version in this repo — see
  commit history / releases for what's been verified since.

## Requirements

- macOS or Linux, Python 3.10+
- Xcode Command Line Tools on macOS if you don't already have them
  (`xcode-select --install`) — `python3 -m venv` needs them
- ~200MB free for the Chromium build `patchright` downloads

## 1. Install

```bash
git clone https://github.com/<you>/naukri-mcp.git
cd naukri-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip   # old pip can't do editable installs from pyproject.toml alone
pip install -e .
python3 -m patchright install chromium
```

## 2. Register it with your MCP client

For Claude Desktop, add an entry to
`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or
the equivalent config on your platform:

```json
{
  "mcpServers": {
    "naukri": {
      "command": "/absolute/path/to/naukri-mcp/.venv/bin/naukri-mcp",
      "args": []
    }
  }
}
```

Get the absolute path with `which naukri-mcp` (venv activated). Restart your
MCP client afterward so it picks up the new server.

## 3. First login

Call the `naukri_login` tool. A real, visible Chrome window opens at
Naukri's login page; log in there yourself (including any OTP/captcha). The
tool polls for up to 5 minutes and saves your session to `~/.naukri-mcp/`
once it detects you're logged in. After that, `naukri_session_status`
reports `logged_in: true` and every other tool runs headless.

## Tool list

| Tool | What it does |
|---|---|
| `naukri_login` | Interactive login handoff |
| `naukri_session_status` | Check if the saved session is still valid |
| `naukri_close_session` | Close the browser to free resources |
| `search_jobs` | Search listings by keywords / location / experience |
| `get_job_details` | Full JD for one job URL |
| `get_recommended_jobs` | Naukri's "recommended for you" list |
| `save_job` | Bookmark a job |
| `get_saved_jobs` | List bookmarked jobs |
| `apply_to_job` | Apply using your existing profile/resume |
| `get_applied_jobs` | List jobs you've applied to |
| `get_my_profile` | Headline, key skills, resume status |
| `get_profile_views` | Who's viewed your profile recently |
| `get_inbox` | Recent recruiter conversations |
| `get_conversation` | Read one conversation's messages |
| `send_message` | Reply to a recruiter |
| `search_companies` | Search the company directory |
| `get_company_profile` | One company's overview/ratings/open roles |

Naukri doesn't have a real equivalent of LinkedIn's social graph (feed,
connections, employee lists), so this isn't a 1:1 port of a LinkedIn-style
MCP server — `apply_to_job` / `get_applied_jobs` / `save_job` /
`get_saved_jobs` reflect Naukri's actual core value (the job pipeline
itself) instead.

## Troubleshooting

**`ModuleNotFoundError: No module named 'mcp.server.fastmcp'`** — you have
`mcp` 2.x, which renamed that module to `mcp.server.mcpserver`
(`MCPServer` replaces `FastMCP`, same `.tool()` / `.run()` API). This repo
already targets 2.x; if you still hit this, check `pip show mcp`.

**A tool returns `raw_text` or a `note` instead of structured data** — a
selector didn't match. Open an issue with the `raw_text` snippet (redact
anything personal) or send a PR against `extract.py` / `tools_*.py`.

## License

MIT — see [LICENSE](LICENSE).