Skip to main content
Glama

HireSquire

PyPI version Python versions CI License: MIT

Unified open-source Python package for HireSquire — AI-powered candidate screening, local resume parsing (PDF, DOCX, TXT, MD), personalized outreach emails, compliance/bias audits, credit management, and interview scheduling.

One install gives you three agent-ready interfaces backed by a single Pydantic v2 schema and resilient HTTP client:

Surface

Entry Point

Best For

Python SDK

from hiresquire import HireSquireClient

Python apps, LangChain, AutoGen, CrewAI, custom workflows

CLI

hiresquire / uvx hiresquire

Shell agents (Claude Code, OpenClaw, Codex), CI/CD, --json pipelines

MCP Server

hiresquire-mcp / hiresquire mcp

Claude Desktop, Cursor, Windsurf, VS Code, any stdio MCP host

Node.js / TypeScript CLI: Prefer npm? Install hiresquire-cli (npx hiresquire-cli).


Installation

pip install hiresquire

Or run zero-install with uvx:

uvx hiresquire whoami --json
uvx --from hiresquire hiresquire-mcp

pypdf and python-docx are core dependencies — PDF and DOCX parsing work out of the box with no extra flags.


Related MCP server: llmconveyors-mcp

Authentication & Configuration

Set your API token (sk_... user token or hs_... spend-limited Agent API key):

export HIRESQUIRE_API_TOKEN="your_token_here"

Or persist it locally (written with mode 0600 to ~/.hiresquire/config.json):

hiresquire init --token YOUR_API_TOKEN

Environment Variable

Precedence

Description

HIRESQUIRE_API_TOKEN

Highest

API token or Agent API key (hs_...)

HIRESQUIRE_BASE_URL

Highest

API base URL (default: https://hiresquireai.com/api/v1)

HIRESQUIRE_WEBHOOK_URL

Highest

Default webhook URL for job completion events

Precedence order: environment variables > ~/.hiresquire/config.json > defaults.


Quick Start

1. MCP Server (Claude Desktop, Cursor, VS Code)

Add to claude_desktop_config.json or .mcp.json using uvx (zero manual install):

{
  "mcpServers": {
    "hiresquire": {
      "command": "uvx",
      "args": ["--from", "hiresquire", "hiresquire-mcp"],
      "env": {
        "HIRESQUIRE_API_TOKEN": "your_token_here"
      }
    }
  }
}

Or if installed via pip install hiresquire:

{
  "mcpServers": {
    "hiresquire": {
      "command": "hiresquire-mcp",
      "env": {
        "HIRESQUIRE_API_TOKEN": "your_token_here"
      }
    }
  }
}

2. Python SDK

from hiresquire import HireSquireClient

with HireSquireClient("YOUR_API_TOKEN") as client:
    # Free health check (no credits spent)
    me = client.whoami()
    print(me["credits"]["formatted_balance"])

    # Submit resumes (local PDF/DOCX/TXT/MD paths or pre-parsed dicts)
    job = client.jobs.create(
        title="Senior Python Developer",
        description="Looking for a backend engineer with 5+ years of Python, FastAPI, and PostgreSQL experience.",
        resumes=["./resumes/john_doe.pdf", "./resumes/jane_smith.docx"],
        leniency_level=6,  # 1 (lenient) to 10 (strict), default 5
    )

    # Poll until completed and fetch ranked candidates
    results = client.jobs.wait(job["job_id"])
    for c in results["candidates"]:
        print(f"{c['id']}: {c['name']} — {c['score']}/100 | {c['summary']}")

    # Generate an interview invite for the top candidate
    top = results["candidates"][0]
    email = client.emails.generate(
        job_id=job["job_id"],
        candidate_id=top["id"],
        email_type="invite",
        tone="professional",
    )
    print(email["subject"], email["body"])

3. CLI (--json ready for agents)

# Free token & balance check
hiresquire whoami --json

# Estimate credit cost before screening
hiresquire estimate --candidates 25 --json

# Submit resumes, poll until completion, and output JSON
hiresquire screen \
  --title "Senior Python Developer" \
  --description "Looking for a backend engineer with 5+ years of Python, FastAPI, and PostgreSQL experience." \
  --resumes ./resumes/ \
  --leniency 6 \
  --watch \
  --json

# Filter results by score or top N
hiresquire results --job 123 --min-score 80 --only-top-n 5 --json

# Generate outreach email
hiresquire email --job 123 --candidate 456 --type invite --tone friendly --json

MCP Tools Reference (26 Tools)

All MCP tools run locally over stdio via FastMCP, extract resume text locally (never uploading raw binary files), and return structured JSON dicts (including {"error": "...", "message": "..."} on failure rather than crashing).

Category

Tool

Key Parameters

Screening

create_screening

title, description (≥50 chars), resume_paths or resumes, leniency_level (1–10), custom_instructions, webhook_url

get_screening_status

job_id

get_results

job_id, min_score, only_top_n

cancel_screening_job

job_id

compare_candidates

job_id, candidate_ids (list of ints)

report_hiring_outcome

job_id, candidate_id, outcome (hired | rejected | withdrawn)

Outreach

generate_email

job_id, candidate_id, email_type (invite | rejection | keep-warm | followup), tone (professional | friendly | formal), custom_notes

bulk_generate_emails

job_id, candidate_ids (max 50), email_type, tone

Credits

get_credit_balance

—

estimate_screening_cost

candidate_count (1–100)

list_credit_packs

—

get_credit_transactions

limit, offset

purchase_credits

amount or pack (pouch | satchel | chest), payment_method_id

create_checkout_session

amount or pack

enable_auto_reload

threshold, amount, payment_method_id

disable_auto_reload

—

Calendar

list_calendar_connections

—

create_calendar_connection

provider (calendly | calcom), api_key, calendar_id

get_available_slots

provider, date, duration

create_interview

job_id, candidate_id, scheduled_at (ISO 8601), duration_minutes, provider

generate_meeting_link

provider, topic, duration

Utilities

whoami

— (free token/balance check)

get_rate_limit

—

test_webhook

url

get_api_schema

—

audit_screening_job

job_id, selection_threshold (default 70)


Python SDK Namespaces

HireSquireClient organizes the API into seven typed namespaces (all validated with Pydantic v2 models in hiresquire.models):

  • client.jobs: create(), create_from_zip(), list(), get_status(), get_results(), wait(), cancel(), compare(), report_outcome()

  • client.candidates: get(), update_status()

  • client.emails: generate(), bulk_generate(), generate_questions(), generate_icebreaker()

  • client.credits: get_balance(), estimate_cost(), list_packs(), get_transactions(), purchase(), create_checkout_session(), create_payment_intent(), enable_auto_reload(), disable_auto_reload()

  • client.calendar: list(), connect(), get_slots(), create_interview(), generate_meeting_link()

  • client.agent_keys: list(), create(), get(), update(), revoke(), regenerate(), get_usage()

  • client.utils: whoami(), get_rate_limit(), test_webhook(), get_api_schema(), audit_screening_job()


Schemas & Contracts (for Agents)

Create Screening Job Request (POST /api/v1/jobs)

{
  "title": "Senior Python Developer",
  "description": "Minimum 50 characters describing role requirements and stack.",
  "resumes": [
    { "filename": "ada_lovelace.pdf", "content": "Extracted resume text..." }
  ],
  "leniency_level": 5,
  "custom_instructions": "Prioritize distributed systems experience",
  "webhook_url": "https://example.com/webhooks/hiresquire"
}
  • Idempotency-Key (UUID v4) is auto-generated and sent as an HTTP header on jobs.create, jobs.create_from_zip, and credits.purchase so retries never double-charge.

  • leniency_level: integer 1 (most lenient) to 10 (strictest), default 5.

  • Resume limits: .txt, .md, .pdf, .docx; max 20 MB per file, max 100 resumes per batch, minimum 50 characters of extracted text.

Screening Results Response (GET /api/v1/jobs/{id}/results)

{
  "job_id": 42,
  "job_title": "Senior Python Developer",
  "status": "completed",
  "total_candidates": 1,
  "candidates": [
    {
      "id": 101,
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "score": 94,
      "summary": "Strong distributed systems and Python background.",
      "strengths": ["10+ years Python", "Event-driven architecture"],
      "weaknesses": ["Limited Kubernetes exposure"],
      "skills": ["Python", "PostgreSQL", "FastAPI"],
      "status": "new"
    }
  ],
  "agent_summary": "1 strong match identified..."
}

Error Hierarchy (hiresquire.errors)

HTTP Status

Exception Class

Code

Notes

401 / 403

AuthenticationError

AUTHENTICATION_ERROR

Missing/invalid token or forbidden job

402

PaymentRequiredError

PAYMENT_REQUIRED

Insufficient credits or agent spend limit reached

404

NotFoundError

NOT_FOUND

Job, candidate, or key not found

400 / 422

ValidationError

VALIDATION_ERROR

Invalid payload (e.g., description < 50 chars)

429

RateLimitError

RATE_LIMIT_ERROR

Automatically retried honoring Retry-After


CLI Command Reference

Pass --json to any command for clean machine-readable output:

hiresquire init              Save token & defaults to ~/.hiresquire/config.json (0600)
hiresquire configure         Update or --clear saved configuration
hiresquire whoami            Verify token and check credit balance (free)
hiresquire estimate          Estimate cost for N candidates
hiresquire screen            Submit resumes (--resumes or --zip, --watch, --leniency)
hiresquire jobs              List screening jobs (--status, --page, --limit)
hiresquire status            Check or --watch job status
hiresquire results           Fetch ranked candidates (--min-score, --only-top-n)
hiresquire summary           Display AI summary for a completed job
hiresquire compare           Compare candidates side-by-side
hiresquire cancel            Cancel a processing job
hiresquire outcome           Report hiring outcome (hired | rejected | withdrawn)
hiresquire candidate         Get candidate details
hiresquire set-status        Update candidate status
hiresquire email             Generate outreach email (--type, --tone, --message)
hiresquire credits ...       balance | list-packs | checkout | purchase | transactions | auto-reload-enable | auto-reload-disable
hiresquire agent-keys ...    list | create | get | update | revoke | regenerate | usage
hiresquire calendar ...      connect | list (also calendar:connect, calendar:list)
hiresquire interviews ...    schedule | list (also interviews:schedule, interviews:list)
hiresquire meetings link     Generate meeting link (also meetings:link)
hiresquire rate-limit        Check API rate limit status
hiresquire webhook-test      Send a test webhook payload
hiresquire schema            Fetch API schema
hiresquire mcp               Start the stdio MCP server

Backward Compatibility (v1 → v2)

Existing v1 code continues to work without changes:

from hiresquire import HireSquire  # alias for HireSquireClient
from hiresquire import create_screening_job, get_hiresquire_tools  # deprecated v1 wrappers

Deprecated top-level functions emit DeprecationWarning and delegate to HireSquireClient.


License

MIT License — see LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A Machine Context Protocol server that enables Claude AI to interact with tools through a structured communication interface, following standard MCP patterns with server initialization and stdio transport.
      2,530 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      This MCP server provides hiring automation tools for recruitment processes. It enables users to generate job descriptions, score CVs, create interview questions, benchmark salaries, and draft offer letters through natural language interactions.
      16 npm
      31 PyPI
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      An MCP server that exposes a perpetual, honest job-application pipeline as typed tools an LLM agent can call, with fit scoring, verified resume building, and a submission planner enforced by code, not prompts.
      16
      80 PyPI
      MIT