job-board-mcp
Allows searching open roles through Greenhouse's official public job board API, returning normalized job listings and full job descriptions.
Enables saving matched jobs to a Notion "Jobs" database and skipping duplicates.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@job-board-mcp find new product manager roles posted this week and save the best one to Notion"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
job-board-mcp
An MCP server that lets Claude search open roles at companies I chose, using their official, public job board APIs (Greenhouse, Lever, and Ashby). It filters roles to my career lanes and reads full job descriptions, so I can ask Claude things like "What deployment roles were posted this week?" and get real, current answers.
I use it every day in my own job search.
Why official APIs instead of scraping
Most job search tools scrape LinkedIn or Indeed, often through proxies to get around blocking. This project does the opposite:
Official APIs only. Greenhouse, Lever, and Ashby publish unauthenticated job board endpoints that are meant to be read. No scraping, no proxies, no logins.
A short list of companies I chose, not the whole internet. The APIs are per company, so this is also the only honest way to use them.
Light on requests. Responses are cached for 15 minutes, at most 8 boards are fetched at once, and every request identifies the project with a
User-Agentthat links back here.No credentials. Nothing to sign up for and no API keys. Clone it and run it.
Related MCP server: JobPilot MCP
Tools
Tool | What it does |
| Lists the configured companies and the ATS each one uses |
| Searches every company's board at once and returns matching jobs in one format, newest first |
| Returns one job's full description as plain text |
Every search result has the same fields, whatever ATS it came from: company, title, location, remote, url, posted_at, ats, job_id, lanes.
If one company's board fails (a wrong slug, a timeout), the search still returns everything else and lists the failure in errors. Individual postings with bad data are skipped and listed in warnings.
Example prompts
"Find deployment roles posted in the last 7 days."
"Show me new grad roles at Decagon or Sierra."
"Any remote PM roles in the last two weeks?"
"Tell me more about the Cohere forward deployed engineer role. Does it fit someone fresh out of a CS degree?"
"Which of my companies are hiring solutions engineers in New York?"
Setup
Requirements: uv and Claude Code. uv installs the right Python version (3.12+) for you.
git clone https://github.com/adeolaoj/job-board-mcp.git
cd job-board-mcp
uv syncRegister the server with Claude Code, using the absolute path to your clone:
# macOS / Linux
claude mcp add job-board -- uv --directory /path/to/job-board-mcp run job-board-mcp
# Windows (PowerShell)
claude mcp add job-board -- uv --directory "C:\path\to\job-board-mcp" run job-board-mcpAdd --scope user before job-board to make it available in every project. Check it with claude mcp list, or type /mcp inside Claude Code.
Add this to claude_desktop_config.json (on Windows: %APPDATA%\Claude\claude_desktop_config.json), then fully restart Claude Desktop:
{
"mcpServers": {
"job-board": {
"command": "uv",
"args": ["--directory", "/path/to/job-board-mcp", "run", "job-board-mcp"]
}
}
}If Claude Desktop can't find uv, use its full path (which uv or where uv).
To try the tools by hand, the MCP Inspector opens a browser UI:
uv run mcp dev src/job_board_mcp/server.pyConfiguration
config/companies.yaml lists the companies to search:
- name: Addepar
ats: greenhouse # greenhouse | lever | ashby
slug: addepar1To find a slug, open one of the company's job postings and read the URL: job-boards.greenhouse.io/{slug}, jobs.lever.co/{slug}, or jobs.ashbyhq.com/{slug}. Check it, don't guess. A wrong slug shows up in errors on every search. The server refuses to start if the file is invalid (unknown ATS, missing field, duplicate name).
config/lanes.yaml defines career lanes as title keywords:
lanes:
deployment:
- forward deployed
- solutions engineer
pm:
- product manager
new_grad:
- new grad
- early career
exclude:
- senior
- staffTitles and keywords are split into words, ignoring case and punctuation, and a keyword matches when its words appear next to each other in the title. So forward deployed matches "Forward-Deployed Engineer", grad does not match "Upgrade", and sr. matches "Sr. Account Executive". A job matching any exclude keyword gets no lane.
How it works
flowchart TD
A["You ask Claude:<br/>'deployment roles from this week'"] --> B["Claude calls search_jobs<br/>(MCP over stdio)"]
B --> C["server.py<br/>check the lane, pick companies"]
C --> D["fetch.py<br/>all boards at once, at most 8 at a time"]
D --> E{"Fetched in the<br/>last 15 minutes?"}
E -- yes --> G
E -- no --> F["Greenhouse / Lever / Ashby API"]
F --> G["Raw JSON per company<br/>(or an error for that company)"]
G --> H["normalize.py<br/>three formats into one Job format"]
H --> I["lanes.py<br/>title into lanes"]
I --> J["search.py<br/>filter, sort newest first, limit"]
J --> K["jobs, total_matches,<br/>warnings, errors"]
K --> L["Claude answers you"]Module | Job |
| MCP tools and the server lifespan (loads config, opens one shared HTTP client) |
| URLs for each ATS, async fetching, status checks, failure isolation |
| A small hand-written cache whose entries expire after 15 minutes |
| Converts each ATS's response into the shared |
| Matches titles to lanes |
| Filters, sorts, and formats results. Pure logic, no network |
| Turns description HTML into readable text, keeping bullet lists |
| Loads and validates |
Design decisions
Every decision was made against real API responses, not documentation alone, and several came from the data disagreeing with what I expected. docs/decisions.md has the full record; some highlights:
The three APIs disagree on almost everything. IDs are integers in Greenhouse and UUID strings elsewhere. Dates are ISO strings with offsets, ISO strings in UTC, or milliseconds since 1970. Greenhouse's descriptions are HTML escaped twice, Lever's plain-text description leaves out responsibilities and qualifications, and Ashby has no public endpoint for a single job.
The docs and the data disagreed too. Lever documents
on-site, but the data saysonsite, so the normalizer accepts both.Lane matching went through three versions. Substring matching put "grad" in "Upgrade" and "intern" in "International". Regex word boundaries couldn't match "Sr." The final version splits titles into words, and the test suite keeps the real titles that broke the first two.
Bad data fails small. A malformed posting is skipped with a warning, a failing company goes in
errors, and the rest of the search still comes back.The cache stores raw JSON, not results, so one cache serves every ATS, and failed requests are never cached.
Testing
uv run pytestThe tests never touch the network:
Fixtures are real API responses, trimmed to a few postings chosen to include edge cases (same title for separate jobs, null remote fields, multi-city postings, double-escaped HTML) and otherwise unedited.
HTTP is faked with
httpx.MockTransport, so tests can return a plain-text 404, a timeout, or invalid JSON.Time is injected. The cache takes a clock and search takes
now, so expiry and "posted within 7 days" tests don't depend on the real date.
Limitations
Lanes match titles only. A good role with an unusual title can be missed, and a keyword can't tell "Research Staff" (a job family) from "Staff Engineer" (a level).
Remote status is often unknown. Greenhouse has no remote field, so it's only known when the location says "Remote".
Only Greenhouse, Lever, and Ashby. Companies on other systems (Workday, or a Notion page) can't be added.
Local only. The server runs on your machine over stdio. Hosting it for claude.ai would need an HTTP transport and authentication.
Roadmap
add_company(careers_url): Claude finds a company, and the server checks its slug with one real request before saving it.new_since_last_check(): only jobs that weren't there on the last run.
License
Available Tools
3 toolsget_jobA
Get one job's full description as plain text, plus its title, location, URL, and posted date.
Pass `company` and `job_id` exactly as they appear in a search_jobs result.
Inputs: job_id (required), company (required).
list_companiesA
List the companies this server searches and which applicant tracking system each uses.
Use these exact names in search_jobs's `companies` filter and in get_job.
Inputs: no named parameters. Returns: result
search_jobsA
Search open jobs across the configured companies' job boards, newest first.
All filters are optional and combine (a job must pass every filter given).
Returns `jobs`, `total_matches` (before `limit`), `errors` (companies that couldn't be
searched, or unknown company names), and `warnings` (individual postings skipped
because of bad data). To read a job's full description, pass its `company` and
`job_id` to get_job.
Inputs: lane, limit, remote, keywords, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool maps to a distinct step of a read-only workflow: list_companies enumerates sources, search_jobs queries them, get_job fetches one full description. Descriptions explicitly cross-reference each other (use these names in search_jobs; pass company/job_id to get_job), leaving no plausible misselection.
All three follow a clean verb_noun snake_case pattern (list_companies, search_jobs, get_job). Verb choice is also semantically precise: list for enumeration, search for filtering, get for single-resource retrieval.
Three tools is the minimum viable surface for discover-sources → search → inspect, and each earns its place with no redundancy. Nothing is padded or missing at the operation level.
The read-only lifecycle is fully covered end to end, including error/warning reporting in search results. Minor gaps: no explicit pagination/offset beyond limit, and no batch job-fetch, so an agent must loop on get_job for multiple postings.
Maintenance
Related MCP Connectors
Run your tech job search from your AI agent: matches, job unlocks, applications and follow-ups.
Job search for your AI: save jobs, research companies, keep stories, track applications.
Track job applications, tailor resumes and draft cover letters from your AI assistant.
1Run your job search from your AI assistant: save jobs, tailor resumes, track applications.
1
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables AI agents to pull live job listings from major ATS platforms (Greenhouse, Lever, Ashby, Workable), Hacker News hiring threads, and detect hiring signals on company career pages.-
- AlicenseAqualityDmaintenanceTransforms Claude into an AI job-hunting assistant that searches remote job boards, scores roles against your CV, generates tailored cover letters, and logs everything to a Notion tracker.11MIT
- FlicenseNot gradedqualityDmaintenanceEnables Claude Desktop to manage a job search end-to-end: find and score job listings, tailor resumes, generate application messages, and track application history, while leaving final external actions to the user.-
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to locate companies' public job boards across Greenhouse, Lever, Ashby and Workable, browse and filter live openings by keyword, location, department and remote status, and read full job descriptions with pay ranges and apply links. Requires no accounts, API keys or authentication, and is read-only.MIT