# Federal Compass Mcp

> Your AI compass from private sector to federal career — MCP server for USAJobs API

- **Type:** MCP server
- **Install:** `agentstack add mcp-skivuha-federal-compass-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [skivuha](https://agentstack.voostack.com/s/skivuha)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [skivuha](https://github.com/skivuha)
- **Source:** https://github.com/skivuha/federal-compass-mcp

## Install

```sh
agentstack add mcp-skivuha-federal-compass-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# federal-compass-mcp

> Your AI compass from private sector to federal career

[](https://npmjs.org/package/federal-compass-mcp)
[](https://github.com/skivuha/federal-compass-mcp/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io)
[](https://scorecard.dev/viewer/?uri=github.com/skivuha/federal-compass-mcp)

Federal job descriptions are 5 pages of legal language. GS grades, clearance levels, hiring paths — none of this is explained anywhere. `federal-compass-mcp` connects Claude to the official [USAJobs API](https://developer.usajobs.gov) and turns it into an AI advisor that speaks plain English.

Built for tech professionals transitioning from private sector to federal/government careers.

---

## What it does

- **Searches** federal job openings with optional filters — keyword, location, salary, clearance level
- **Translates** federal job descriptions into plain language — what they actually want, without the jargon
- **Analyzes** your CV against specific job postings and tells you if you qualify
- **Explains** federal concepts — GS grades, pay plans, security clearances, hiring paths
- **Saves** your CV locally so Claude can reference it automatically

---

## Getting started

### 1. Get your free USAJobs API key

Register at [developer.usajobs.gov](https://developer.usajobs.gov/apirequest/index) — takes about 3 minutes. Verify your email and you'll receive an API token.

### 2. Add to your MCP client

**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "federal-compass": {
      "command": "npx",
      "args": ["-y", "federal-compass-mcp@latest"],
      "env": {
        "USAJOBS_API_KEY": "your_api_key",
        "USAJOBS_EMAIL": "your@email.com"
      }
    }
  }
}
```

**VS Code / Cursor / Windsurf** — same config, different config file path. See your client's MCP documentation.

### 3. Try it

```
Find me senior software developer jobs in Raleigh, NC
```

```
What is a GS-13 and how much does it pay?
```

```
Save my CV [attach file]
```

```
Look at this job posting — am I qualified?
```

---

## Tools

| Tool | Description |
|------|-------------|
| `search_jobs` | Search federal job openings. All filters optional — keyword, location, salary, grade, agency, remote |
| `get_job_details` | Get full details for a specific job posting |
| `compare_jobs` | Compare 2-5 job postings side by side |
| `save_cv` | Save your CV locally for automatic use in analysis |
| `get_cv` | Read your saved CV |
| `explain_federal_concept` | Explain GS grades, clearances, hiring paths, pay plans |
| `calculate_salary` | Calculate GS salary with locality pay for any grade, step, and location |
| `find_matching_jobs` | Find jobs matching your CV — extracts skills and searches USAJobs |
| `check_qualification` | Compare your CV against a specific job posting |
| `extract_ksa` | Extract KSA requirements from a job posting, optionally match against your CV |

---

## CV storage

Your CV is stored locally on your machine — never sent to any server:

```
~/.federal-compass/
  cv.json
  config.json
  codelists/     <- cached USAJobs reference data
```

---

## Why federal jobs are confusing (and how this helps)

Coming from private sector, federal job postings feel like a different language:

- **GS-13 Step 1-10** — what grade am I? what does step mean?
- **TS/SCI with polygraph** — do I need this? how long does it take?
- **Competitive vs Excepted Service** — which one can I apply to?
- **HiringPath: fed-transition** — what is this and why does it matter?

`federal-compass-mcp` answers all of these through natural conversation with Claude.

---

## Requirements

- Node.js v22+
- Free [USAJobs API key](https://developer.usajobs.gov/apirequest/index)
- Any MCP-compatible client (Claude Desktop, VS Code, Cursor, etc.)

---

## Contributing

Issues and PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).

---

## License

MIT — see [LICENSE](LICENSE)

---

*Built by [@skivuha](https://github.com/skivuha) — a Senior Frontend Engineer navigating the private-to-federal transition firsthand.*

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [skivuha](https://github.com/skivuha)
- **Source:** [skivuha/federal-compass-mcp](https://github.com/skivuha/federal-compass-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-skivuha-federal-compass-mcp
- Seller: https://agentstack.voostack.com/s/skivuha
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.