resume-ats-mcp

A local Model Context Protocol server that turns Claude Desktop into an ATS (Applicant Tracking System) resume checker. It plugs in as a connector: Claude calls it as a tool mid-conversation, the server does the parsing/scoring, and Claude narrates the result.

What it does

Two tools, exposed over MCP:

Formatting audit — parses the file and flags things that break real ATS parsers: tables, text in headers/footers, embedded images, non-extractable ("scanned image") PDFs, page count.

Keyword match — when a job description is supplied, extracts candidate keywords from it (capitalized phrases, tech tokens like CI/CD or .NET, and frequently-repeated terms) and checks which ones appear in the resume, word-boundary-safe (so CI won't false-match inside "efficient"). Returns a matched/total percentage plus the explicit missing-keyword list.

This is a heuristic, not a certified ATS engine — it's regex/frequency-based, with no LLM call inside the tool itself. The value is in feeding structured, deterministic signal to Claude, which then reasons over it in the conversation.

Related MCP server: Career Compass MCP

Architecture

flowchart LR
    subgraph Claude Desktop
        UI[Chat UI] --> Model[Claude]
    end
    Model -- "MCP stdio\n(JSON-RPC over stdin/stdout)" --> Server[server.py\nMCPServer instance]
    Server --> Parse[pypdf / python-docx\nfile parsing]
    Server --> Score[keyword extraction\n+ formatting audit]
    Server -- reads --> FS[(Resume files\non disk)]

Claude Desktop launches server.py as a child process and talks to it over stdio using JSON-RPC — this is the "local connector" pattern in MCP, as opposed to a remote HTTP/SSE connector. No network port, no auth: the process only exists while Claude Desktop is running, and only your local machine can reach it.

How the connector is registered

Claude Desktop reads ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) on startup. Adding a mcpServers entry tells it what command to spawn:

{
  "mcpServers": {
    "resume-ats": {
      "command": "/absolute/path/to/mcp-server/.venv/bin/python",
      "args": ["/absolute/path/to/mcp-server/server.py"],
      "env": {
        "RESUME_ATS_DIR": "/absolute/path/to/your/resumes"
      }
    }
  }
}

• command/args — point at the venv's Python interpreter directly (not a bare python3), so the server always runs with its own installed dependencies regardless of what's active in your shell.

• env.RESUME_ATS_DIR — the only machine-specific configuration. It sets the default directory list_resume_files browses, without hardcoding a personal path into the source code.

After editing the config, fully quit (Cmd+Q) and reopen Claude Desktop — it only reads this file at launch.

Implementation notes

• Built on mcp[cli] — the official Python MCP SDK. @mcp.tool() decorates a plain function; its type hints and docstring become the tool's schema and description, which is what the model sees when deciding whether/how to call it.

• stdio is the default transport (mcp.run()), matching what Claude Desktop's local-connector launcher expects.

• File parsing is dispatched by extension: pypdf for .pdf, python-docx for .docx, plain read for .md/.txt.

• Keyword matching uses a lookaround-based regex ((?<![A-Za-z0-9])keyword(?![A-Za-z0-9])) rather than str.count(), to avoid substring false-positives on short tokens.

Setup

git clone <this-repo>
cd mcp-server
python3 -m venv .venv
./.venv/bin/pip install -r requirements.txt

Then add the mcpServers entry above to claude_desktop_config.json, pointing command/args at this checkout and RESUME_ATS_DIR at wherever your resumes live. Restart Claude Desktop.

Testing without Claude Desktop

The MCP SDK ships a client you can drive directly, which is how this was verified during development:

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    params = StdioServerParameters(command="./.venv/bin/python", args=["server.py"])
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            print(await session.list_tools())
            print(await session.call_tool("list_resume_files", {}))

asyncio.run(main())

Limitations

• Keyword extraction is heuristic (regex + frequency), not semantic — it won't recognize "led a team" as matching a JD's "leadership," for example.

• No OCR: image-based/scanned PDFs will correctly be flagged as low-text but can't be scored.

• Single-machine, single-user: this is a local stdio connector, not a hosted service.

License

MIT