# openroles

> openroles is an open-source MCP server for hiring and recruiting. Pull open roles straight from employers' own applicant tracking systems, no API key. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, Linux, macOS, Windows, API
- **Repository:** https://github.com/aranculleton/openroles
- **MCP Registry name:** io.github.aranculleton/openroles
- **Categories:** [hiring and recruiting](https://ai-powered.com/categories/hiring-and-recruiting), [web search and scraping](https://ai-powered.com/categories/web-search-and-scraping)
- **Listing updated:** 2026-11-18

## About

Job boards lag and repost stale listings, so openroles reads the feeds that companies' own careers pages already use. Fifteen systems are supported: Greenhouse, Lever, Ashby, Workday, Workable, Teamtailor, Personio, Recruitee, Rippling, JazzHR, Gem, Polymer, Manatal, Homerun and ClearCompany. A careers site that publishes jobs for search engines also works. Every role comes back in the same shape with the employer's real apply link.

It is a Python library first, with a command line and an MCP server layered on top. The library respects robots.txt, can cache with ETag and Last-Modified so unchanged boards send nothing, and has a helper that lists the hosts a firewall must allow. Postings are checked for text hidden from human readers, which the README notes is sometimes written for a model.

Start the MCP server with openroles mcp. It has two tools, and descriptions are left out unless requested to keep answers short.

## Features

- **Fifteen ATS sources:** Reads Greenhouse, Lever, Ashby, Workday and eleven other systems in one format.
- **Board detection:** Finds an employer's board from a name, careers page, board URL or ats:token.
- **Search filters:** Filter by title words, location, remote only and days since posting.
- **Polite caching:** Honours robots.txt and uses ETag or Last-Modified to skip unchanged boards.
- **Hidden text report:** Flags text in a posting that no human reader would see.
- **Standard library only:** Python 3.9 or newer, no dependencies, no account.

## Good for

- Check every open role at a target company
- Monitor several employers for new postings in a city
- Build a job-matching agent that cites the employer's own apply link
- Work out which hosts a network policy must allow for job feeds

## Install

### Claude Code (Terminal)

```sh
claude mcp add openroles -- uvx openroles
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "openroles": {
      "command": "uvx",
      "args": [
        "openroles"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "openroles": {
      "command": "uvx",
      "args": [
        "openroles"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "openroles": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "openroles"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "openroles": {
      "command": "uvx",
      "args": [
        "openroles"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "openroles": {
      "command": "uvx",
      "args": [
        "openroles"
      ]
    }
  }
}
```

## Tools

- `find_job_board`: Find an employer's job boards and how each was found.
- `list_open_roles`: List open roles, with descriptions only when asked.

## FAQ

### Does it need an API key?

No. It needs no key or account and uses only the Python standard library.

### How do I start the MCP server?

Run openroles mcp, for example claude mcp add openroles -- uvx openroles mcp.

### Which tools does the server expose?

find_job_board and list_open_roles.

### Does it respect robots.txt?

Yes. fetch raises RobotsDisallowed when the host's robots.txt says no.

### Is openroles free?

Yes. openroles is open source, so you can use and self-host it for free.

### How do I add openroles to Claude Code?

Run this command in your terminal: claude mcp add openroles -- uvx openroles

### What are the best alternatives to openroles?

The closest alternatives to openroles are Scrapling MCP Server, Firecrawl MCP Server, Douyin_TikTok_Download_API, SearXNG Search and Reactive Resume.

## Where this comes from

- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [Scrapling MCP Server](https://ai-powered.com/mcp/scrapling-mcp-server): Scrapling MCP Server is an open-source MCP server for web search and scraping.
- [Firecrawl MCP Server](https://ai-powered.com/mcp/firecrawl-mcp-server): Firecrawl MCP Server is a freemium MCP server for web search and scraping.
- [Douyin_TikTok_Download_API](https://ai-powered.com/mcp/douyin-tiktok-download-api): Douyin_TikTok_Download_API is an open-source MCP server for web search and scraping.
- [SearXNG Search](https://ai-powered.com/mcp/searxng-search): SearXNG Search is an open-source MCP server for web search and scraping.
- [Reactive Resume](https://ai-powered.com/mcp/reactive-resume): Reactive Resume is an open-source MCP server for hiring and recruiting.
- [machine_internet](https://ai-powered.com/mcp/machine-internet): machine_internet is an open-source MCP server for web search and scraping.
- [acrawl](https://ai-powered.com/mcp/acrawl): acrawl is an open-source MCP server for browser automation.
- [Countries](https://ai-powered.com/mcp/countries): Countries is a freemium MCP server for web search and scraping.

---
Source: https://ai-powered.com/mcp/openroles
