Recruit CRM MCP

MCP (Model Context Protocol) server for Recruit CRM, enabling AI assistants to search candidates, view jobs, and manage recruiting workflows.

Quick Start

One-Click Install (recommended)

macOS / Linux — run in Terminal:

curl -LsSf https://raw.githubusercontent.com/ebragas/recruitcrm-mcp/main/install.sh | bash

Windows — run in PowerShell:

powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/ebragas/recruitcrm-mcp/main/install.ps1 | iex"

The installer will:

• Install uv if you don't have it

• Prompt for your Recruit CRM API key

• Back up your existing Claude Desktop config

• Add the Recruit CRM MCP server entry

macOS / Linux:

curl -LsSf https://raw.githubusercontent.com/ebragas/recruitcrm-mcp/main/install.sh -o install.sh
cat install.sh   # review the script
bash install.sh

Windows:

Invoke-WebRequest -Uri https://raw.githubusercontent.com/ebragas/recruitcrm-mcp/main/install.ps1 -OutFile install.ps1
Get-Content install.ps1   # review the script
powershell -ExecutionPolicy Bypass -File .\install.ps1

Already have uv? You can skip the bootstrap and run the installer directly:

uvx --from recruit-crm-mcp recruit-crm-mcp-install

Manual Setup

If you prefer to configure manually, add to your claude_desktop_config.json:

{
  "mcpServers": {
    "recruit-crm": {
      "command": "uvx",
      "args": ["--refresh-package", "recruit-crm-mcp", "recruit-crm-mcp"],
      "env": {
        "RECRUIT_CRM_API_KEY": "your-api-key-here"
      }
    }
  }
}

Why --refresh-package? Without it, uvx caches the installed venv and reuses it indefinitely — you'd stay on whichever version was installed first, even after we publish bug fixes. The flag forces uvx to re-fetch the package's PyPI index entry on each Claude Desktop launch (~100 ms warm) and pull a newer version when available. Auto-updates without you running anything.

Installing a pre-release (test) build

Pre-release builds (e.g. 0.16.0rc1) are published to PyPI for internal testing. They are not picked up by the default installer or by a bare uvx recruit-crm-mcp — you have to pin them explicitly.

To run a pre-release once from the command line:

uvx recruit-crm-mcp@0.16.0rc1

To use a pre-release with Claude Desktop, edit claude_desktop_config.json and change the args entry to include the version pin:

{
  "mcpServers": {
    "recruit-crm": {
      "command": "uvx",
      "args": ["recruit-crm-mcp@0.16.0rc1"],
      "env": {
        "RECRUIT_CRM_API_KEY": "your-api-key-here"
      }
    }
  }
}

Fully quit and reopen Claude Desktop (the app keeps running in the dock after closing the window).

To roll back to stable, set args back to ["--refresh-package", "recruit-crm-mcp", "recruit-crm-mcp"] (or pin a specific stable like ["recruit-crm-mcp@0.15.0"]) and restart Claude Desktop.

Why other users are safe. uvx's default resolver strategy is --prerelease=if-necessary: pre-releases are skipped unless no stable version satisfies the spec. Because recruit-crm-mcp has a stable release on PyPI, the unpinned uvx recruit-crm-mcp in the default installer's config resolves to the latest stable and never picks up a pre-release. Only an explicit pin like @0.16.0rc1 opts in.

Development

uv sync              # install dependencies
make test            # run tests
make lint            # run linter
make check           # run lint + tests

Tools

Candidates

Jobs

Contacts

Companies

Notes / Tasks / Meetings

Assignments

Files

Users / Lookups

Feedback

Resources

Configuration

Set environment variables in your MCP client config (e.g. claude_desktop_config.json's env block):

Error reporting

Two complementary, fully optional channels for surfacing problems:

1. report_issue MCP tool (always available)

When something goes wrong and you want to send a structured bug report, ask Claude to "report this issue" or "file a bug." The MCP exposes a report_issue tool that builds a prefilled GitHub Issues URL — Claude returns the link, you click it, GitHub opens the new-issue form pre-populated with the summary, the last error, and your environment details. Submit it from your browser like any other issue. Works with any GitHub account; no token in the MCP, no collaborator access needed, repo is public.

2. Sentry auto-capture (bring-your-own-DSN)

If you want passive observability — every tool-call exception captured automatically with stack trace, span context, and HTTP breadcrumbs, plus a populated MCP Dashboard showing which tools your users actually call — set RECRUIT_CRM_MCP_SENTRY_DSN to a Sentry project DSN that you control. With no DSN set (the default), the MCP makes zero network calls to Sentry.

This is strictly bring-your-own-DSN. We do not publish or embed a project DSN. If you want this, sign up for a free Sentry account, create a Python project, copy its DSN, and put it in your MCP client config:

{
  "mcpServers": {
    "recruit-crm": {
      "command": "uvx",
      "args": ["--refresh-package", "recruit-crm-mcp", "recruit-crm-mcp"],
      "env": {
        "RECRUIT_CRM_API_KEY": "...",
        "RECRUIT_CRM_MCP_SENTRY_DSN": "https://<key>@<org>.ingest.sentry.io/<project>"
      }
    }
  }
}

What you get in your Sentry project:

• Errors. Tool name, exception type, stack trace, HTTPX breadcrumbs (URLs and status codes), MCP request/session IDs, and the package version.

• Usage telemetry. Every tool invocation is captured as a span (traces_sample_rate defaults to 1.0), tagged with tool name, arguments, result, duration, and transport. These populate Sentry's MCP Dashboard — per-tool request count, error rate, p95 latency, client distribution. This is how you find out which tools your users actually use.

Recruit CRM data flowing through tools (candidate names, emails, company info) will appear in span and event payloads — that's the point, since both errors and usage analysis are unhelpful without the data that triggered them. Because the DSN is yours, the data only goes to your Sentry project.

If transaction volume is a concern (free Sentry plans cap at 5K events/month), set RECRUIT_CRM_MCP_SENTRY_TRACES_RATE=0.2 for 20% sampling, or 0.0 to disable tracing entirely while keeping error capture.

Privacy

• No telemetry by default. With no Sentry DSN configured, the MCP makes zero network calls to anyone except api.recruitcrm.io.

• No DSN is bundled. We do not embed our own Sentry DSN — Sentry capture only works if you supply your own.

• report_issue is explicit-consent. It only builds a clickable URL; nothing is sent until you submit the prefilled form in your browser.

• Public repo issues. Reports filed via report_issue are publicly visible on GitHub. Don't paste secrets or PII you wouldn't want public.