# remotive-mcp-server

An [MCP](https://modelcontextprotocol.io) server that gives Claude (or any MCP client) two tools for searching [Remotive](https://remotive.com)'s public remote-job board: `remotive_search_jobs` and `remotive_get_job`. No API key or signup required — Remotive's job endpoint is free and public.

Built as a small, focused demo of MCP server design: real API integration, defensive handling of an upstream quirk, Pydantic-validated inputs, and a verifiable evaluation set.

## What it does

- **`remotive_search_jobs`** — search current Remotive listings by keyword and/or category, returns a compact markdown or JSON digest (title, company, category, tags, location, salary, post date, apply URL).
- **`remotive_get_job`** — given a job id from a search result, returns the full listing including the plain-text job description.

Example prompts once connected to Claude:
- "Find remote Rails jobs on Remotive and summarize the top 3."
- "Pull the full description for job 2069746."
- "What DevOps roles are open right now, and what do they pay?"

## A real-world gotcha this server works around

Remotive's public `/api/remote-jobs` endpoint sits behind a Cloudflare cache that, in testing, keyed its cache **only on the request path — not the query string**. Every request, regardless of `search`, `category`, or `limit` params, returned an identical cached response (confirmed via the `cf-cache-status: HIT` response header and byte-identical results across differing params).

To make filtering actually work for callers, this server fetches the full current listing and applies `search`/`category` filtering **client-side** rather than trusting the upstream query params. See the comment at the top of `server.py` for details.

## Setup

```bash
git clone <this-repo>
cd remotive-mcp-server
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
```

### Run standalone (stdio)

```bash
.venv/bin/python server.py
```

### Connect to Claude Desktop / Claude Code

Add to your MCP client config (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "remotive": {
      "command": "/absolute/path/to/remotive-mcp-server/.venv/bin/python",
      "args": ["/absolute/path/to/remotive-mcp-server/server.py"]
    }
  }
}
```

Restart your client and the `remotive_search_jobs` / `remotive_get_job` tools will be available.

## Evaluation

`evaluation/evaluation.xml` has 10 verifiable question/answer pairs exercising both tools (including ones that require calling `remotive_search_jobs` to find a job id, then `remotive_get_job` to read facts only present in the full description). Remotive's listing changes daily, so the pinned answers are a snapshot from 2026-08-10 — regenerate them against the live API before relying on this for regression testing.

## Attribution & fair use

Per [Remotive's API terms](https://remotive.com/api-documentation), every tool response includes a link back to the original Remotive job URL and credits Remotive as the source. This server does not cache or redistribute job data beyond a single request/response cycle, and calls the endpoint only on demand (Remotive asks for at most a few requests per day since data refreshes slowly).

## Stack

Python 3.10+, [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk), `httpx`, `pydantic`.

## License

MIT — see [LICENSE](LICENSE).