federal-compass-mcp

Your AI compass from private sector to federal career

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 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

2. Add to your MCP client

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

config.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

Code

Find me senior software developer jobs in Raleigh, NC

Code

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

Code

Save my CV [attach file]

Code

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:

Code

~/.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
Any MCP-compatible client (Claude Desktop, VS Code, Cursor, etc.)

Contributing

Issues and PRs welcome. See CONTRIBUTING.md.

License

MIT — see LICENSE

Built by @skivuha — a Senior Frontend Engineer navigating the private-to-federal transition firsthand.