mcp-lever

<img src="assets/icon-128.png" alt="" width="96" align="right">

# mcp-lever

[![npm](https://img.shields.io/npm/v/mcp-lever.svg)](https://www.npmjs.com/package/mcp-lever)
[![CI](https://github.com/smeet666/mcp-lever/actions/workflows/ci.yml/badge.svg)](https://github.com/smeet666/mcp-lever/actions/workflows/ci.yml)
[![license](https://img.shields.io/npm/l/mcp-lever.svg)](./LICENSE)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-6E56CF)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.smeet666/mcp-lever)
[![Glama](https://glama.ai/mcp/servers/smeet666/mcp-lever/badges/score.svg)](https://glama.ai/mcp/servers/smeet666/mcp-lever)
[![M8ven](https://m8ven.ai/badge/mcp/smeet666-mcp-lever-ti7zmm?variant=verified)](https://m8ven.ai/mcp/smeet666-mcp-lever-ti7zmm)
[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=lever&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1sZXZlciJdfQ%3D%3D)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=lever&config=%7B%22name%22%3A%22lever%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mcp-lever%22%5D%7D)
<!-- m8ven-verify: 5faf86e7541e0167239ba83df2f3a7cc -->

An MCP server for the public job boards companies publish through
[Lever](https://www.lever.co). Search the openings of the companies you name,
read one in full, and see the wordings each company filters by. No API key, no
account, read-only.

[Français](#mcp-lever-français)

## What it does

Lever hosts one job board per company, and publishes no index across them. Every
question therefore starts with a company name, and this server turns that name
into the site name that addresses its board.

```
resolve_company(["Included Health"])  ->  includedhealth, global instance, publishing
search_jobs(["Included Health"], keyword: "therapist")
get_job("includedhealth", "6f97a19f-…")
```

## Install

```bash
npx mcp-lever
```

Claude Desktop, `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "lever": {
      "command": "npx",
      "args": ["-y", "mcp-lever"]
    }
  }
}
```

### With Docker

```json
{
  "mcpServers": {
    "lever": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-lever:2.0.0"]
    }
  }
}
```

`-i` keeps stdin open, which is where the protocol travels, and no `-t` is
passed: a TTY rewrites the stream and breaks it. The container needs outbound
HTTPS to `api.lever.co` and `api.eu.lever.co`, and nothing else: no volume, no
port, no environment variable, no credential.

## The tools

### `resolve_company`

Company names in, the Lever site names out, with every instance that answered. It
takes a list, because probing ten names costs ten resolutions where a search
would read ten boards.

Lever site names distinguish case: `Flex` answers where `flex` returns 404. Four
spellings are tried on each of Lever's two instances, stopping at the first one
confirmed. **Nothing found is never proof that a company is absent from Lever**,
and the answer says so, listing the spellings that were sent.

### `search_jobs`

`companies` is required, and takes names or site names. Each name is resolved
here, so no preparation is needed.

| Filter                                                                     | Applied by                           |
| -------------------------------------------------------------------------- | ------------------------------------ |
| `location`, `team`, `department`, `commitment`                             | Lever, on its exact wording          |
| `keyword`, `workplace_type`, `country`, `salary_min`, `posted_within_days` | this server, on the openings it read |

Lever offers no full-text search and accepts no filter on workplace type,
country or salary, which is why those are applied here. `limit` applies per
company, and a company whose openings fill it may publish more: the notes say
when that happened, and that a count taken inside that window measures the
window.

`posted_within_days` walks up to five pages per company. Lever pages by title,
so an opening published yesterday sits anywhere in a board, and a recency
question read from the first page answers about the first page.

### `get_job`

One opening in full: the advert, its named sections, and the salary as
published. A search returns rows without the text, because one company's board
runs to megabytes.

### `list_filter_values`

The team, location and commitment wordings one company uses. Read it before
filtering: Lever matches its own wording, and **answers a wording it does not
know with an empty list and no error**, which reads as "nothing found". The
vocabulary belongs to each company: one writes `Full-time`, another `Full Time`,
another `EE Full-Time`.

## What the answers never claim

- **A salary Lever does not publish is `null`**, never zero. Most openings
  publish none, and filtering on salary drops them: the notes say how many.
- **An amount carries its own period.** A rate published per hour is never
  annualised, and a threshold is only compared against amounts sharing its
  period. Nothing is converted between currencies.
- **A country Lever does not record is `null`**, never another country. Openings
  carrying no country are counted separately when a country filter drops them.
- **A site name that does not exist, a site publishing nothing, and a read that
  failed are three answers**, and `per_company` says which is which.
- **No result count.** Lever publishes none, so `total_available` is always
  `null`, and a full page is no measure of what exists.

## What it reads, and what it leaves alone

The server reads `api.lever.co` and `api.eu.lever.co`, which Lever documents as
public and whose `robots.txt` allows everything with `Crawl-delay: 1`. It sends
one request at a time, a second apart, under a `User-Agent` naming the project
and a contact address.

It never reads `jobs.lever.co`, whose `robots.txt` names six agents and refuses
each of them. Openings carry the address of their page there, because citing an
address is not crawling it.

## Stability

A major version covers what a caller writes against and reads back:

- the four tool names, and the names and types of their arguments;
- the shape of what each tool returns, and the fields it carries;
- the six error codes;
- the `./client` subpath: `Client`, `Read<T>`, and the shapes it hands back.

These stay minor, and a caller who reads only what it asked for is untouched:

- a new optional argument, or a new tool;
- a new field in an answer, or a new note;
- the wording of a note, a description, or an error message;
- following a newer revision of the Model Context Protocol, which changes the
  envelope around the tools rather than the tools.

A field that Lever stops publishing is reported as absent rather than removed
from the shape, so a schema never narrows without a major version.

## Use it as a library

The low-level client is published on its own, with the pacing, the cache and the
error taxonomy, and no protocol attached:

```js
import { Client } from "mcp-lever/client";

const client = new Client();
const { found } = await client.resolveCompany("Aircall");
const { data } = await client.listPostings({ slug: found[0].slug, instance: "global" });
```

Errors carry one of six codes: `not_found`, `invalid_input`, `rate_limited`,
`parse_failure`, `network_error`, `timeout`. A failure is never returned as an
empty result.

## Licence

MIT. Job adverts belong to the companies that published them: credit the company
and link the page each opening carries.

---

# mcp-lever (français)

Un serveur MCP pour les pages carrières que les entreprises publient à travers
[Lever](https://www.lever.co). Cherchez les offres des entreprises que vous
nommez, lisez-en une en entier, et consultez le vocabulaire de filtre propre à
chacune. Sans clé d'API, sans compte, en lecture seule.

## Ce qu'il fait

Lever héberge une page carrières par entreprise et ne publie aucun index qui les
traverse. Toute question part donc d'un nom d'entreprise, que ce serveur
transforme en identifiant de site.

```
resolve_company(["Included Health"])  ->  includedhealth, instance globale, publie
search_jobs(["Included Health"], keyword: "therapist")
get_job("includedhealth", "6f97a19f-…")
```

## Installation

```bash
npx mcp-lever
```

Claude Desktop, dans `claude_desktop_config.json` :

```json
{
  "mcpServers": {
    "lever": {
      "command": "npx",
      "args": ["-y", "mcp-lever"]
    }
  }
}
```

### Avec Docker

```json
{
  "mcpServers": {
    "lever": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-lever:2.0.0"]
    }
  }
}
```

`-i` garde l'entrée standard ouverte, qui est le canal du protocole, et aucun
`-t` n'est passé : un terminal réécrit le flux et le casse. Le conteneur a
besoin d'un accès HTTPS sortant vers `api.lever.co` et `api.eu.lever.co`, et de
rien d'autre : aucun volume, aucun port, aucune variable d'environnement, aucun
identifiant.

## Les outils

### `resolve_company`

Des noms d'entreprises en entrée, leurs identifiants de site en sortie, avec
chaque instance qui a répondu. L'outil prend une liste, parce que sonder dix noms
coûte dix résolutions là où une recherche lirait dix pages carrières.

Les identifiants distinguent la casse : `Flex` répond là où `flex` rend 404.
Quatre formes sont essayées sur chacune des deux instances, en s'arrêtant à la
première confirmée. **Ne rien trouver ne prouve jamais qu'une entreprise est
absente de Lever**, et la réponse le dit, en listant les formes envoyées.

### `search_jobs`

`companies` est requis et accepte des noms ou des identifiants. Chaque nom est
résolu ici, sans préparation.

| Filtre                                                                     | Appliqué par                    |
| ----------