Lets an AI client search and retrieve open job roles directly from employer applicant tracking systems like Greenhouse, Lever, and Workday.
Also known as aranculleton/openroles
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- 1,157
- Latest version
- 0.5.1
- Last commit
- Nov 11, 2026
- License
- MIT
What is openroles MCP?
openroles lets an AI client search and retrieve open job roles directly from employer applicant tracking systems like Greenhouse, Lever, and Workday.
Summary generated from the project's README
About openroles MCP server
openroles allows AI clients to search and retrieve job openings directly from employer applicant tracking systems. Instead of relying on third-party job boards that may contain stale information, this tool connects to the original source of truth. It supports fifteen different systems including Greenhouse, Lever, Ashby, Workday, and Rippling, as well as general careers sites that publish jobs for search engines.
Developers can use this as a Python library or via a command line interface. When used as an MCP server, it provides tools like find_job_board and list_open_roles to Claude, Cursor, and other compatible agents. The setup is lightweight, requiring only Python 3.9 or newer and no external API keys or accounts. It works by reading the JSON, RSS, or XML feeds that employers use for their own careers pages, ensuring the data is current and includes direct application links.
What you can do with it
- 1Search for specific rolesAn AI agent can find data engineering positions at a specific company using a query parameter.
- 2Filter jobs by locationA developer can instruct an agent to find job openings located specifically in New York.
- 3Identify employer tracking systemsAn agent can detect which applicant tracking system a company uses and find its specific board token.
Written from the project's README. Every use case is checked against a quote from it.
How to install openroles MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall openroles MCP in Claude Code
$ claude mcp add openroles -- uvx openrolesInstall openroles MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"openroles": {
"command": "uvx",
"args": [
"openroles"
]
}
}
}Install openroles MCP in VS Code
.vscode/mcp.json
{
"servers": {
"openroles": {
"type": "stdio",
"command": "uvx",
"args": [
"openroles"
]
}
}
}Install openroles MCP in VS Code CLI
$ code --add-mcp '{"name":"openroles","type":"stdio","command":"uvx","args":["openroles"]}'Install openroles MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"openroles": {
"command": "uvx",
"args": [
"openroles"
]
}
}
}Install openroles MCP in Codex
$ codex mcp add openroles -- uvx openrolesInstall openroles MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.openroles] command = "uvx" args = ["openroles"]
Install openroles MCP in Gemini CLI
$ gemini mcp add -s user openroles uvx -- openrolesInstall openroles MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"openroles": {
"command": "uvx",
"args": [
"openroles"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablearanculleton/openroles is public and reachablegithub.com/aranculleton/openroles ↗Pass
- Package names this repository as its sourceopenroles names aranculleton/openroles as sourcepypi.org/project/openroles/ ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for openrolespypi.org/project/openroles/ ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-11github.com/aranculleton/openroles ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from openrolesPass
- No critical advisory in the package or its dependenciesthe package checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubopenroles
Every open role, straight from the employer's own careers system. Fifteen applicant tracking systems (Greenhouse, Lever, Ashby, Workday, Workable, Teamtailor, Personio, Recruitee, Rippling, JazzHR, Gem, Polymer, Manatal, Homerun and ClearCompany), plus any careers site that publishes its jobs for search engines, in one shape. Read from the feeds and APIs the employers' own careers pages use: no API key, no account, no scraping service, and nothing but the Python standard library.
$ pip install openroles
$ openroles figma --query data --limit 3
2026-09-23 Data Engineer Intern (2027) San Francisco, CA • New York, NY https://boards.greenhouse.io/figma/jobs/6178851004?gh_jid=6178851004
2026-09-21 Data Platform Engineer San Francisco, CA • New York, NY • Unite https://boards.greenhouse.io/figma/jobs/6201407004?gh_jid=6201407004
2026-09-21 PhD Intern, Data Science (2027) San Francisco, CA • New York, NY https://boards.greenhouse.io/figma/jobs/6200626004?gh_jid=6200626004
3 open role(s)
Give it a company name, a careers page, a board URL or ats:token. It finds the board,
reads every open role, and gives you the same fields whichever system the employer uses.
Why
Job sites miss roles, show them late, and repost them stale. The employer's own board is
the source: it is complete, current, and carries the real apply link. Most applicant
tracking systems publish that board as JSON, RSS or XML for the employer's own careers
page. openroles reads it the same way, politely, and puts every system that allows it
behind one function.
Install
pip install openroles # or: uvx openroles <company>
Python 3.9 or newer. No dependencies.
Command line
openroles linear # every open role at Linear
openroles https://jobs.ashbyhq.com/linear # the same, from the board URL
openroles lever:zoox --query "data" --since 14 # title words, posted in the last 14 days
openroles figma --location "New York" # filter by place (--remote for remote only)
openroles https://adobe.wd5.myworkdayjobs.com/external_experienced \
--query "data scientist" --details # Workday, with each posting's description
openroles detect "Figma" # which ATS, and the board's token
openroles hosts greenhouse:figma lever:zoox # the hosts to allow in a network policy
openroles personio:acme # any system, as ats:token
openroles careersite:careers.acme.example # a careers site with no job API
openroles linear --json > roles.json # JSON (the default when piped), or --jsonl
openroles linear --cache ~/.cache/openroles # an unchanged board sends nothing next run
Python
import openroles
boards = openroles.detect("Figma")
# [Board(ats='greenhouse', token='figma'), Board(ats='ashby', token='figma')]
[b.found for b in boards]
# ['guessed', 'guessed']: boards under a name Figma might use; 'linked' from a careers page
jobs = openroles.fetch("greenhouse:figma", query="data", location="New York")
for job in jobs:
print(job.posted, job.title, job.location, job.url)
job.to_dict() # plain JSON-ready dict
openroles.hosts("personio:acme")
# ['acme.jobs.personio.de', 'acme.jobs.personio.com']: what a firewall must allow
openroles.job_id("https://www.acme.example/careers/?gh_jid=4012345")
# 'gh-4012345': the same id fetch() gives that posting, from its address alone
job.hidden says what was left out of a posting's description because no reader sees it,
such as {"hidden elements": 2, "tag characters": 40}, and is {} for most. Text hidden
from people is often written for a model, so it is worth a look before one reads the
posting.
job_id is for matching one posting found in two places, read from the employer's board
and linked from a job site. It reads Greenhouse (any page with gh_jid too), Lever,
Ashby, Rippling, Workable, Personio and Workday addresses, fetches nothing, and gives ""
for an address that does not carry the system's own posting id. One Workday case is
ambiguous: a listing that sends its path already percent-encoded ("M%C3%BCnchen") gives
the same address as one that sends it plain ("München"), and job_id reads it as the
plain one.
fetch() raises openroles.BoardError when a board cannot be read (a wrong token, no
answer), and openroles.RobotsDisallowed when the host's robots.txt says no.
In your own application
openroles is a library first: the CLI and the MCP server are thin layers over fetch and
detect. An application that embeds it names itself once, at start-up:
openroles.configure(
user_agent="acme-jobs/1.0 (+https://acme.example/contact)", # sent with every request
robots_agents=["acme-jobs"], # a Disallow for your agent stops a read too
cache_dir="~/.cache/acme-jobs/openroles", # optional: keep answers between runs
)
With cache_dir, each board's last answer is kept with the ETag or Last-Modified date
the board sent, and the next run asks with them: a board that honours them and has not
changed answers 304 Not Modified and sends nothing, and the kept copy is read instead.
An answer that came with a Last-Modified date and no ETag is asked about that way for
at most a day (MODIFIED_MAX_AGE in openroles._http, 24 hours) after it was last read
in full, and then read in full once, so a host whose date does not move when its data
does holds a board back a day at most; the same holds within one run, with or without a
folder. Every read still asks the board. It is off by default. An answer is kept only when it is
a GET, is not marked no-store, and shows that all of it arrived: all of its
Content-Length, every chunk of a chunked answer, or a gzip stream to its end. One that
gives no length and is neither chunked nor gzipped ends when the connection closes, cut
short or not, so it is read in full every time. Kept answers are in owner-only files, for
30 days unused, and about 500 MB of them: each process keeps the folder to that, so two
processes writing to one folder at once (a long-running application and a command-line
run, say) can take it past that until one of them next looks at the whole folder: when it
starts using it, at least once an hour while it does, and whenever what it has written
itself passes the cap.
Everything a search decides for itself stays a parameter: query, location, remote,
since_days, country, and details, which can be a function that says which postings
are worth a request for their description. report={} comes back filled with what failed
on each board. openroles.robots_allows(host, paths) answers the same robots.txt question
openroles asks itself, for anything else your application fetches.
For AI agents (MCP)
openroles mcp is a Model Context Protocol server over
stdio, so Claude, Cursor and other agents can look up any employer's open roles
themselves. Two tools: find_job_board (each board with how it was found, so a guess is
not taken for the employer's own) and list_open_roles (descriptions left out unless
asked for, to keep answers short).
Claude Code:
claude mcp add openroles -- uvx openroles mcp
Claude Desktop, Cursor and other clients (mcpServers in their config):
{
"mcpServers": {
"openroles": { "command": "uvx", "args": ["openroles", "mcp"] }
}
}
There is also llms.txt, a short brief for a model that has to use the
library or the CLI.
What you get
Every role, from every system, has the same fields:
| Field | |
|---|---|
id |
stable across runs: a prefix for the system (gh-, lv-, ab-, wd-, ...) plus its own id |
ats, board |
where it came from, e.g. greenhouse, figma |
title, url |
the role and its apply page |
location, locations |
every location the posting lists, joined and as a list |
workplace |
remote, hybrid, onsite, or "" when the board does not say |
remote |
True, False, or None when the board does not say (hybrid is None) |
posted |
YYYY-MM-DD, first published (not last edited) where the system says; see below |
department, employment_type |
where the board provides them |
compensation |
the posted pay band, where the employer publishes one, as the board words it |
salary_min, salary_max, salary_currency, salary_period |
the same band as numbers, its ISO currency code and hour, day, week, month, year or "" (a period such as every two weeks), only where the board publishes them as numbers (Lever, Ashby, Recruitee, Rippling, ClearCompany, careers sites); never read out of a description |
deadline |
where the board provides one |
description |
plain text: HTML removed, and with it what no page shows (comments, scripts, hidden elements, Unicode tag characters); an element is hidden by the hidden attribute, aria-hidden="true", or an inline style that hides it (display: none, visibility: hidden, opacity: 0, font-size: 0, color: transparent, a clip that leaves nothing, a place far off the page, a height of 0 with its overflow hidden); job.hidden says what was left out, and is not part of to_dict() |
Supported systems
| System | Requests | Notes |
|---|---|---|
| Greenhouse | 1 per board | descriptions; a posting's offices count as its locations only where its own location names no place ("Hybrid", a time zone): an office is the employer's tag, not where the job is |
| Lever | 1 per board | descriptions with their requirement lists; EU boards found automatically |
| Ashby | 1 per board | descriptions and posted pay. Ashby publishes no first-posted date, so posted is when the posting was last published |
| Workday | 1 per 20 roles, plus 1 per description | --query searches the board, reading on while titles keep matching; --country narrows it by whatever facet the board files countries under; --details fetches descriptions, only for roles whose title passes --query |
| Workable | 1 per board | descriptions; no pay. Built from Workable's documentation and not yet run against a live board (its hosts were rate-limiting when it was written) |
| Teamtailor | 1 per 100 roles | descriptions; hybrid and remote; a careers site on the employer's own domain works too |
| Personio | 1 per board | descriptions in English where the employer wrote them; .de and .com accounts |
| Recruitee | 1 per board | descriptions, pay and closing dates. From 10 February 2027 Recruitee asks for each employer's own token, after which a board reads as needing it |
| Rippling | 1 per board, plus 1 per description | descriptions and dates come from each posting's own record, fetched only with --details or a --query, at most 80 a board and 90 in any ten minutes across boards (Rippling allows 100 requests in 10 minutes) |
| JazzHR | 1 per board | descriptions; no date or pay. The feed is regenerated once a day |
| Gem | 1 per board | descriptions; hybrid and remote |
| Polymer | 1 per 20 roles, plus 1 per description | pay; descriptions as for Rippling, at most 60 a board |
| Manatal | 1 per 100 roles | descriptions; no date |
| Homerun | 1 per board | descriptions and pay, from the feed every Homerun careers page links to |
| ClearCompany | 1 per board | descriptions and pay; the token is the site id the careers page prints. Only its first page is read, with a warning when there is more |
Any careers site (careersite) |
1 per sitemap, plus 1 per job page | reads the schema.org JobPosting each job page carries for search engines (iCIMS and Eightfold sites, among others), at most 40 pages a call, newest first |
A Workday posting listed as "3 Locations" reads as its primary location "and 2 more"; with
--location on a place that is not its primary, its page is read to see whether the place
is one of the others. Workday pages a board only to its first 2,000 roles: past that, a
warning says to search with --query.
detect finds a board from a company name (every system but Workday and ClearCompany,
by trying the names an employer is likely to use), from any board URL, and from a careers
page that links to or embeds one, however the page writes it. Each board says how it was
found (Board.found): named (its URL or ats:token was given), linked (the careers
page links to it) or guessed (a board exists under a name the employer might use). A
guess can be a stranger's board that took the name first, so confirm it from the
employer's careers page; openroles detect says so on stderr. A Workday board cannot be
guessed from a name: give its URL (either tenant.wdN.myworkdayjobs.com or
wdN.myworkdaysite.com/recruiting/tenant). A careers site is never guessed: name it as
careersite:<address>. When a careers page uses a system openroles cannot read (any in
the table below), a warning names it and says why.
Not supported, and why
Each was checked before it was left out. A system moves onto the list above when it publishes an open board its own terms and robots.txt allow.
| System | Why not |
|---|---|
| SmartRecruiters | its robots.txt closes its public API to every crawler except LinkedIn's |
| SuccessFactors, Dayforce, UKG, Paycom, Pinpoint | robots.txt disallows the job pages, or the board needs a sign-in |
| BambooHR, Breezy | their terms forbid automated reading of the careers pages |
| Cornerstone, BrassRing, Hireology, Comeet | the board is read through a session token issued to the browser |
| Phenom | the sites checked ask, through robots.txt's Content-Signal, that their content not be used as AI input |
| Oracle Recruiting | its job API is marked for internal use, and the job pages build their JobPosting in the browser |
| Freshteam | being shut down by its vendor |
| iCIMS, Eightfold | no open job API, but their careers sites usually publish JobPosting pages: read them as careersite: |
| Taleo, ADP, Paylocity, JOIN, TalentLyft, ApplicantPro, Jobvite | not yet checked well enough to build a reader on |
Polite by design
- robots.txt is read first, and a refusal is honoured, never worked around. Where the vendor documents its endpoint as a public API (Greenhouse, Lever, Workable, Teamtailor, Personio, Recruitee, Rippling, JazzHR, Gem, Polymer, Manatal), an explicit Disallow stops a read and a robots.txt that cannot be read does not. Everywhere else (Ashby, Workday, Homerun, ClearCompany, any careers site) robots.txt must be readable and must allow the read. For Workday the careers site's own rules count too.
- A site that asks not to be AI input is not read. robots.txt's
Content-Signal: ai-input=nois honoured, because openroles is often run by an AI agent. - A redirect is followed only where its new host's robots.txt allows it, and never more than five times.
- A host's
Crawl-delayis kept between requests once its robots.txt is read (Lever asks for one second), and a robots.txt is read again after a day, as RFC 9309 asks. - At most two requests in flight per host, a timeout on every call, gzip on the wire,
conditional requests (
ETagandLast-Modified) for anything read twice in a run, and across runs with a cache folder, and an honestUser-Agentnaming this project. - XML that declares a DTD or entities is never parsed, so a hostile feed cannot expand.
- A host that answers 429 or 503 is sent nothing more until the pause its
Retry-Afternames has passed, or for ten minutes when it names none, from any board read from it; a request in that time is not sent, and says so. A documented rate limit (Rippling's 100 requests in 10 minutes) is kept below across every board read from the host in a process, and a request past it is not sent either.
Is this allowed?
Most of these systems document their endpoints as public, for exactly this purpose:
showing an employer's open roles somewhere else. Each reader's source file quotes the
vendor's own words and says where they are. Workday's, Ashby's, Homerun's and
ClearCompany's are the endpoints their own careers pages call; they are not documented,
they can change without notice, and openroles reads them only where robots.txt allows.
A careers site is read only from the job pages it publishes for search engines, at the
pace its robots.txt asks. Use it the way the boards are
meant to be used: to find roles and apply to them, at a human pace. It is not a tool for
hammering a site or republishing someone's board wholesale.
Where it came from
openroles is the employer-board reader from
last-job-search, a job search that Claude
runs end to end, extracted so anyone can use it.
Contributing
Contributions are welcome, and the most useful one is a reader for another system, or a check that moves one off the "Not supported" list. CONTRIBUTING.md has the set-up, the few rules that keep the library small and polite, and a checklist for adding a system. Bugs and requests go in Issues.
pip install -e . pytest ruff
pytest && ruff check . # offline: every answer comes from tests/fixtures/
Licence
MIT. See LICENSE.
openroles MCP questions
How do I add openroles MCP to Claude Code?
Run claude mcp add openroles -- uvx openroles in your terminal. Add --scope user to make it available in every project.
How do I add openroles MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does using openroles require an API key?
No, it reads from the feeds and APIs that employers' own careers pages use without requiring an API key or an account.
What job boards are supported?
It supports fifteen applicant tracking systems including Greenhouse, Lever, Ashby, Workday, Workable, Teamtailor, Personio, Recruitee, Rippling, JazzHR, Gem, Polymer, Manatal, Homerun, and ClearCompany.