Recruiter Roles Mcp

io.github.pcmartsPublished by GitHub account pcmartsv1.0.0Updated Oct 25, 2026

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

VerifiedStreamable HTTPWeb executableWeb Search & ScrapingData & AnalyticsBusiness & Commerce

Overview

AI-generated overview

Read-only MCP server for the Recruiter Roles job board, letting an assistant search live recruiter jobs, companies, sectors, locations and market stats.

What you can do
  • Search and filter live recruiter and talent-acquisition job listings by sector, location, employment type, work arrangement, salary and recency, with paginated results and apply links
  • Fetch full detail for a single job, including description, requirements, benefits, tech stack and apply contact
  • Browse recruiting companies and agencies, filter them by name, type or HQ country, and get a company profile with its active jobs
  • List sectors and the location hierarchy (countries, regions, cities) with active job counts, to build filter values
  • Retrieve aggregate market stats: total active jobs, posting velocity and breakdowns by sector, employment type, work arrangement and country
When to use it
Useful when someone wants an assistant to research the recruiting and talent-acquisition job market: finding open roles, comparing agencies, or pulling current hiring statistics without browsing the board manually.
Requirements
A free Recruiter Roles API key, supplied as the RECRUITER_ROLES_API_KEY environment variable for the local npm package or in an Authorization header (or key query parameter) for the hosted endpoint. The local option needs Node.js to run via npx; the hosted option needs network access to the provider's endpoint.
Before you install
The API key is a credential and is forwarded to the provider's REST API; keep it out of shared config files where possible. Usage shares the REST API limit of 1,000 requests per day per key. Any page or product publishing data obtained through the server must include a visible link back to Recruiter Roles, and keys may be suspended if that backlink is removed. All tools are read-only.

Installation

In SourceWeft

  1. Open Recruiter Roles Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.pcmarts%2Frecruiter-roles-mcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "recruiter-roles": {
      "type": "http",
      "url": "https://recruiterroles.com/api/mcp"
    }
  }
}

README

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.

Tools

ToolDescription
search_jobsSearch & filter live jobs (sector, location, salary, remote, recency, full-text).
get_jobFull detail for one job — description, requirements, benefits, apply contact.
list_companiesBrowse recruiting agencies & employers with active job counts.
get_companyA company profile plus its active jobs.
list_sectorsAll recruiting sectors with live job counts.
list_locationsCountries, regions, and cities with live job counts.
market_statsAggregate 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:

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

Gemini CLI — this repo is also a Gemini CLI extension that wires up the hosted server. Install it and enter your key when prompted (it is stored in the system keychain, never in a file):

bash
gemini extensions install https://github.com/pcmarts/recruiter-roles-mcp

To add or change the key later: gemini extensions config recruiter-roles-mcp.

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 installnpm run buildRECRUITER_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.

Source: README.md at commit 3e9d6c5

Tools

7

search_jobs

Search recruiter 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.

Parametersqcitypagesortstatesectorper_pageis_remotesalary_minsource_typeposted_sinceupdated_since+3 more

get_job

Get job detail

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

Parametersslugrequired

list_companies

List recruiting companies

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

Parametersqpagesortcountryper_pagecompany_type

get_company

Get company profile

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

Parameterspageslugrequiredper_page

list_sectors

List sectors

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

Takes no parameters.

list_locations

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.

Parameterslevelregioncountry

market_stats

Recruiter job market stats

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

Takes no parameters.

Version history

1
  1. v1.0.0LatestSep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts