Run Sweepy from an AI assistant with MCP

An AI assistant can run Sweepy for you. You describe the role you want, and the assistant calls Sweepy on your behalf instead of asking you to type terminal commands.

That connection uses the Model Context Protocol (MCP). MCP is a shared language that lets an AI assistant use tools installed on your computer. Sweepy includes a built-in MCP server in server.py. It runs over stdio transport, so it talks to your client locally and doesn't open a network port.

note

MCP is optional. Sweepy works fully from terminal commands without any AI assistant. The server adds a conversational layer on top of the same engine. It also adds the model's judgement and intelligence to the deterministic scoring and filtering that Sweepy already performs.

Before you connect

• Finish Installation so Python and Sweepy's dependencies are in place. The mcp and anyio packages arrive with requirements.txt.
• Note the absolute path to server.py. You paste that path into your client's configuration.
• Restart your AI client after you change its MCP configuration.

Available tools

Sweepy exposes twelve tools to your assistant. Each one returns a JSON payload and declares read-only, destructive, idempotent, and open-world hints.

Tool	What it does
create_profile	Builds, validates, and saves a YAML profile from a PDF or DOCX resume.
run_sweep	Runs the five-stage pipeline in the background and stores deterministic cards.
get_sweep_status	Waits on a running sweep and reports its progress.
get_jobs	Returns the cards held in the current session, ranked by score.
submit_judgments	Replaces a card's deterministic fields with your assistant's judgment.
import_jobs	Appends jobs your assistant verified elsewhere.
render_report	Renders the cards PDF from the current session.
get_results	Reads the most recent sweep result from disk.
export_report	Rebuilds PDF, PNG, CSV, or JSON files from an existing sweep.
clear_history	Forgets reported postings for one profile.
convert_document	Converts a supported document to PDF.
convert_docx	Converts a DOCX resume to PDF.

The MCP tool reference goes into further detail. It lists each parameter, default, payload, and behavior hint.

Choose job search engines

When you omit sources_config, create_profile enables the built-in JobSpy and ATS engines. It also enables optional engines that have a working install and valid defaults. The tool returns enabled_engines and engines_not_enabled, so you can see which engines run and which still need setup.

OpenRoles searches only the company boards you list. Add company slugs before you enable it. Apify may incur charges. Enable it if you wish. Sweepy doesn't install optional packages automatically. You don't need to select engines for every search. Choose explicitly only when an engine needs setup, paid-service consent, or a search constraint.

Pass sources_config when you choose engines explicitly. Sweepy keeps that selection instead of adding other engines. This JSON selects two engines:

{
  "enabled": ["jobspy", "openroles"],
  "openroles": {"companies": ["figma", "stripe"]}
}

One-shot and hybrid tool flows

Sweepy runs in two patterns. Pick the one that matches how much you want the assistant to decide.

One-shot flow. Your assistant configures and runs everything, and the engine scores every role by resume keyword overlap.

create_profile -> run_sweep -> get_results -> export_report (optional)

Hybrid stateful flow. Your assistant reviews each card and supplies its own judgment before the report renders.

run_sweep -> get_jobs -> submit_judgments -> render_report

A live sweep can keep running after a client timeout. When run_sweep returns sweep_status: "running", call get_sweep_status with the returned job_id until it reports completed. Then continue with get_jobs.

tip

You don't need an LLM for a working report. The run_sweep tool alone renders the full cards PDF from deterministic fields, exactly like a terminal sweep.

Each card shows one of two score labels:

• NN% KEYWORD OVERLAP comes from the deterministic engine. It compares your resume text against each posting.
• NN% MATCH comes from your assistant. It appears when you call submit_judgments with a match_pct value.

Verify and supplement sweep results

Treat every sweep result as a starting set, then verify each match against the posting. After run_sweep, inspect skipped_sources and report source failures. Review roles with get_jobs, then compare each posting with your resume and stated preferences before your assistant submits an LLM judgment.

When your assistant has web or search tools, ask it to verify promising roles on employer career pages or their ATS. It can also search for relevant roles Sweepy missed, add verified non-duplicate postings through import_jobs, and include those roles in the report with render_report. Your assistant must not invent postings or fill missing job details with guesses.

Sweepy's URL checker keeps some URLs as unverified when a host blocks access, rate limits requests, or times out. A 403 or 429 doesn't prove a posting expired. Confirm the listing on an accessible employer source when possible, or treat it as unverified. If your assistant has no search tool, or sources remain inaccessible, disclose that the results may be incomplete. Avoid repeating a sweep with unchanged settings after an error.

Connecting to Antigravity or Claude Desktop

Add Sweepy to your client's MCP configuration file, named mcp_config.json or claude_desktop_config.json depending on the client:

mcp_config.json

{
  "mcpServers": {
    "sweepy": {
      "command": "python",
      "args": [
        "/path/to/sweepy/server.py"
      ]
    }
  }
}

Replace /path/to/sweepy with the absolute path to your Sweepy folder, then restart the client. Once registered, you can ask for work like this:

• "Create a Sweepy profile for Alex searching for remote Technical Writer roles in New York. The resume is at path/to/resume.pdf."
• "Run a sweep with the writer profile and show the top 5 matches."
• "Regenerate the PDF from the last pedro_writer sweep and save it to the Desktop."
• "Convert path/to/notes.md to PDF next to the original file."

Writing outside the Sweepy folder

Every write tool stays inside your Sweepy folder by default. A request to save into the Desktop fails until you set the SWEEPY_ALLOW_EXTERNAL_WRITES environment variable to 1.

Connecting to VS Code

VS Code connects to MCP servers without an extra extension:

1. Open the Command Palette and run MCP: Add Server.
2. Choose Command (stdio), then enter python as the command. Add the absolute path to server.py as its argument.
3. Name the server sweepy, then choose the configuration destination.
4. Confirm the Sweepy tools appear in the chat panel, then call them from there.

For a workspace-scoped file, add .vscode/mcp.json to your project. The VS Code format uses a top-level servers object:

.vscode/mcp.json

{
  "servers": {
    "sweepy": {
      "type": "stdio",
      "command": "python",
      "args": [
        "/path/to/sweepy/server.py"
      ]
    }
  }
}

Install the /sweepy skill

Sweepy provides a /sweepy skill for Copilot CLI, Claude Code, Antigravity, and other command-line tools that read skills. Copy the bundled folder into your tool's skills directory:

Terminal

cp -r skills/sweepy ~/.claude/skills/sweepy   # adjust to your tool's skills path

Register the MCP server from the preceding section, then restart your tool. The skill documents three core flows:

• Start a new scrape by calling create_profile, then run_sweep.
• View the results of a scrape by calling get_results for top matches and playbooks, or get_jobs for the full card set.
• Export the results to a CSV file by calling export_report with formats=["csv"].

The skill also covers the fallback for command-line tools without MCP support:

Terminal

sweepy --setup                         # interactive profile wizard
sweepy --profile profiles/your_profile.yaml
sweepy --docx resume.docx              # convert a DOCX resume to PDF
sweepy --convert notes.md              # convert any supported document to PDF

Set up everything with one prompt

Copy this prompt and paste it into any AI command-line session or IDE chat:

Set up Sweepy on this machine. Complete these steps in order:

1. Clone or download the Sweepy repository.
2. Run `pip install -r requirements.txt` in the repository root.
3. Register `server.py` in the MCP configuration as a stdio server. Use the command `python` and args pointing at `server.py`.
4. Copy the `skills/sweepy` folder into the CLI's skills directory.

Learn more prompting patterns

The repository's AGENTS.md documents tool sequencing, per-tool guidance, and prompting patterns. Read it if you want deeper automation than the flows on this page.