# kcdevs-mcp

An [MCP](https://modelcontextprotocol.io) server for the **Kansas City software-developer job
market**. It lets AI assistants (Claude, Cursor, Windsurf, ChatGPT, etc.) search live KC dev jobs,
look up hiring companies, and pull real salary and demand statistics.

Powered by [kcdevs.com](https://kcdevs.com). All data is served remotely — nothing runs locally and
no API key is required.

## Install / run

### Local (stdio) — Claude Desktop and most MCP clients

```jsonc
{
  "mcpServers": {
    "kcdevs": {
      "command": "npx",
      "args": ["-y", "kcdevs-mcp"]
    }
  }
}
```

### Remote (Streamable HTTP)

The same server can run as a remote HTTP endpoint, so clients that support remote MCP can connect
without installing anything:

```bash
MCP_TRANSPORT=http PORT=8080 npx kcdevs-mcp
# → POST http://localhost:8080/mcp   (stateless JSON-RPC)
# → GET  http://localhost:8080/health
```

## Tools

### `search_jobs`
Search live KC-area developer jobs (and KC-based remote roles).

| Param | Type | Description |
| --- | --- | --- |
| `q` | string | Keyword (title, company, description). |
| `category` | enum | `frontend` `backend` `fullstack` `mobile` `devops` `data` `qa` `design` `management` `other`. |
| `skill` | string | Skill slug, e.g. `react`, `python`, `aws`. |
| `experience` | enum | `junior` `mid` `senior` `lead` `principal`. |
| `remote` | enum | `remote` `hybrid` `onsite`. |
| `salary_min` | number | Minimum advertised salary in USD. |
| `posted_within` | enum | `24h` `3d` `7d` `30d`. |
| `sort` | enum | `newest` (default) or `salary`. |
| `per_page` | number | 1–50 (default 25). |

### `get_job`
Full detail of one job by its `id` (slug from `search_jobs`) — description, salary, skills, apply link.

### `list_companies`
KC companies with open developer roles, ordered by number of openings.

### `get_company`
One company by its `id` (slug from `list_companies`) — overview, HQ, typical roles, top-hired skills,
and current open roles.

### `market_stats`
Live snapshot of the KC developer job market: active jobs, companies hiring, median + interquartile
advertised salary (USD, suppressed under 20 data points), demand by category, most in-demand skills,
and the remote/hybrid/on-site mix.

**Example agent uses:** "Find senior backend jobs in Kansas City paying over $130k," "Which KC
companies are hiring React developers?", "What's the median developer salary in Kansas City right
now?"

## Config

- `KCDEVS_API_BASE` — override the job-data API base (default `https://kcdevs.com`).
- `MCP_TRANSPORT` — `stdio` (default) or `http`.
- `PORT` / `MCP_PATH` — port and path for HTTP mode (default `8080` / `/mcp`).

## Data

Backed by the public read-only API at `https://kcdevs.com/api/v1` (`/jobs`, `/companies`, `/stats`).
Read-only; per-IP rate limited.

## License

MIT