# Federal Compass MCP

Wires USAJobs into your AI agent so it can search federal openings, decode the legalese in postings and work out GS pay.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 12
- Author: skivuha
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/skivuha/federal-compass-mcp
- Updated: 2026-10-21
- HTML: https://affpapa.org/en/nevibecode/mcp/federal-compass-mcp

## What it does

The server hands the agent a set of tools on top of the official USAJobs API. `search_jobs` filters openings by keyword, place, salary, grade, agency or remote status; `get_job_details` pulls one posting in full; `compare_jobs` lines up two to five side by side. A separate tool, `explain_federal_concept`, unpacks GS grades, steps, security clearances and hiring paths that postings never bother to define.

Career switchers get `calculate_salary`, which works out GS pay including the locality adjustment for a given grade, step and place. Your CV stays on disk at `~/.federal-compass/cv.json`: `save_cv` writes it, `get_cv` reads it, `find_matching_jobs` lifts skills out of it to hunt for matches, `check_qualification` measures it against one posting, and `extract_ksa` pulls the KSA requirements. CV text goes back to your MCP client, and depending on the client's setup it may then reach a model provider.

Register a free key at developer.usajobs.gov and pass it with your email as `USAJOBS_API_KEY` and `USAJOBS_EMAIL`; the tools cannot authenticate without them. Node.js 22 or later is required. CV scoring and requirement matching are unofficial analysis, so confirm deadlines and instructions on the live USAJOBS announcement before you apply.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `USAJOBS_API_KEY`, `USAJOBS_EMAIL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env USAJOBS_API_KEY=<USAJOBS_API_KEY> --env USAJOBS_EMAIL=<USAJOBS_EMAIL> --transport stdio federal-compass-mcp -- npx -y federal-compass-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add federal-compass-mcp --env USAJOBS_API_KEY=<USAJOBS_API_KEY> --env USAJOBS_EMAIL=<USAJOBS_EMAIL> -- npx -y federal-compass-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "federal-compass-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "federal-compass-mcp"
            ],
            "env": {
                "USAJOBS_API_KEY": "<USAJOBS_API_KEY>",
                "USAJOBS_EMAIL": "<USAJOBS_EMAIL>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "federal-compass-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "federal-compass-mcp"
            ],
            "env": {
                "USAJOBS_API_KEY": "<USAJOBS_API_KEY>",
                "USAJOBS_EMAIL": "<USAJOBS_EMAIL>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e USAJOBS_API_KEY=<USAJOBS_API_KEY> -e USAJOBS_EMAIL=<USAJOBS_EMAIL> federal-compass-mcp npx -y federal-compass-mcp
```
Replace <…> with your own values

## When to use it
- search federal openings by keyword and city
- find out what a GS-13 is and what it pays where you live
- stack several job postings next to each other
- test your CV against one posting's requirements
- pull KSA requirements out of a long announcement

## Example prompts
- Find federal developer openings in Raleigh, North Carolina
- Explain GS-13 and what the pay looks like
- Save my CV and tell me whether I qualify for this posting

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md