Recruiter Roles MCP

Official7 tools

by pcmarts · TypeScript

Search Recruiter Roles: live recruiter jobs, companies, sectors, locations, and market stats.

Search live recruiter job listings, companies, sectors, locations, and labor market data.

Captured live from the server via tools/list.

search_jobs

Search live recruiter and talent-acquisition job listings on Recruiter Roles. Supports full-text search and filtering by sector, location, employment type, work arrangement, salary, and recency. Returns a paginated list with salary, company, location, and a tracked apply URL.

Parameters (15)

qstring
Full-text search across job title and company name.
sectorstring
Sector slug, comma-separated for multiple (e.g. 'technology,financial-services'). Use list_sectors for valid slugs.
statestring
State/region code, comma-separated (e.g. 'TX,NY,BC'). Use list_locations for codes.
citystring
City slug, comma-separated (e.g. 'dallas-tx').
employment_typestring
Employment type filter.
work_arrangementstring
Work arrangement filter.
is_remoteboolean
Shorthand for work_arrangement=remote.
salary_mininteger
Minimum salary in USD. Only returns jobs with a disclosed salary at or above this.
salary_disclosedboolean
true = only jobs with a disclosed salary; false = only undisclosed.
source_typestring
'direct' = employer-posted, 'scraped' = aggregated.
posted_sincestring
ISO date — jobs posted on or after this date.
updated_sincestring
ISO datetime — for incremental sync; jobs updated on or after this.
sortstring
Sort order. Default: recent.
pageinteger
Page number. Default: 1.
per_pageinteger
Results per page. Default: 20, max: 100.

get_job

Fetch the full detail for a single job by its slug, including the complete description, requirements, benefits, tech stack, and apply contact.

Parameters (1)

slugstringrequired
The job slug (the last path segment of its URL, or the 'slug' field from search_jobs).

list_companies

Browse the directory of recruiting companies and agencies with their active job counts. Filter by name, company type, or HQ country.

Parameters (6)

qstring
Search company name.
company_typestring
Company type filter.
countrystring
HQ country code (e.g. 'US', 'GB').
sortstring
Sort order. Default: job_count.
pageinteger
Page number. Default: 1.
per_pageinteger
Results per page. Default: 20, max: 100.

get_company

Fetch a single company's full profile plus a paginated list of its active jobs.

Parameters (3)

slugstringrequired
The company slug (e.g. 'robert-half').
pageinteger
Page of the company's jobs. Default: 1.
per_pageinteger
Jobs per page. Default: 20, max: 100.

list_sectors

List all recruiting sectors with their current active job counts. Use the returned slugs for the 'sector' filter in search_jobs.

No parameters.

list_locations

List the location hierarchy (countries, regions, or cities) with active job counts. Use the returned codes/slugs for the 'state' and 'city' filters in search_jobs.

Parameters (3)

levelstring
Hierarchy level to return. Default: countries.
countrystring
Filter by country code (e.g. 'US', 'GB').
regionstring
Filter cities by region code (e.g. 'TX'). Use with level=cities.

market_stats

Aggregate market overview: total active jobs, posting velocity (24h / 7d), and breakdowns by sector, employment type, work arrangement, and country.

No parameters.

README.md4 KBView on GitHub

Recruiter Roles MCP server

Query the Recruiter Roles job board from any MCP-capable AI client (Claude, Cursor, ChatGPT, VS Code, …). Ask in plain language and get live recruiter and talent-acquisition jobs, company profiles, sectors, locations, and market stats — straight from the board.

Read-only. Authenticated with a free Recruiter Roles API key.

Hosted (recommended): https://recruiterroles.com/api/mcp (Streamable HTTP)
Local (this package): npx recruiter-roles-mcp (stdio, for stdio-only clients)
Get a free API key: https://recruiterroles.com/api-access
Docs: https://recruiterroles.com/mcp · REST API: https://recruiterroles.com/api-docs

Tools

Tool	Description
`search_jobs`	Search & filter live jobs (sector, location, salary, remote, recency, full-text).
`get_job`	Full detail for one job — description, requirements, benefits, apply contact.
`list_companies`	Browse recruiting agencies & employers with active job counts.
`get_company`	A company profile plus its active jobs.
`list_sectors`	All recruiting sectors with live job counts.
`list_locations`	Countries, regions, and cities with live job counts.
`market_stats`	Aggregate market overview — totals, posting velocity, and breakdowns.

All tools are annotated readOnlyHint: true, destructiveHint: false, openWorldHint: false, and expose an outputSchema.

Connect

Hosted remote server (recommended)

Most clients can connect directly to the hosted Streamable HTTP endpoint with your API key in the Authorization header (or as a ?key= query param for clients that can't set headers).

Cursor — ~/.cursor/mcp.json:

json

{
  "mcpServers": {
    "recruiter-roles": {
      "url": "https://recruiterroles.com/api/mcp",
      "headers": { "Authorization": "Bearer rr_live_YOUR_KEY" }
    }
  }
}

VS Code — .vscode/mcp.json:

json

{
  "servers": {
    "recruiter-roles": {
      "type": "http",
      "url": "https://recruiterroles.com/api/mcp",
      "headers": { "Authorization": "Bearer rr_live_YOUR_KEY" }
    }
  }
}

Claude / ChatGPT custom connector — add the URL with your key appended:

code

https://recruiterroles.com/api/mcp?key=rr_live_YOUR_KEY

Local stdio server (this npm package)

For stdio-only clients or local development. Set your API key via the RECRUITER_ROLES_API_KEY environment variable:

json

{
  "mcpServers": {
    "recruiter-roles": {
      "command": "npx",
      "args": ["-y", "recruiter-roles-mcp"],
      "env": { "RECRUITER_ROLES_API_KEY": "rr_live_YOUR_KEY" }
    }
  }
}

Run it directly:

bash

RECRUITER_ROLES_API_KEY=rr_live_YOUR_KEY npx recruiter-roles-mcp

How it works

This is a thin, read-only layer over the public Recruiter Roles v1 REST API. Each tool forwards your API key to one GET /api/v1/* endpoint, so MCP usage shares the same rate limit (1,000 requests/day per key), caching, and request logging as the REST API. The server holds no database connection and no secrets of its own.

Develop

bash

npm install
npm run build
RECRUITER_ROLES_API_KEY=rr_live_YOUR_KEY node dist/index.js

Optional: point at a different origin during development with RECRUITER_ROLES_BASE_URL (default https://recruiterroles.com).

Backlink policy

Any page or product that publishes data obtained through this server must include a visible, crawlable link back to Recruiter Roles. Keys may be suspended if the backlink is removed.

License

MIT — see LICENSE.

Install

Tools (7)

search_jobsget_joblist_companiesget_companylist_sectorslist_locationsmarket_stats

Configuration

Environment variables

RECRUITER_ROLES_API_KEYrequiredsecret

Your Recruiter Roles API key (rr_live_...). Get one free at https://recruiterroles.com/api-access

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "recruiter-roles-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "recruiter-roles-mcp@1.0.0"
      ],
      "env": {
        "RECRUITER_ROLES_API_KEY": "<YOUR_RECRUITER_ROLES_API_KEY>"
      }
    }
  }
}