About Federal Compass MCP
Federal Compass MCP connects an MCP client to the USAJOBS API for people moving from private-sector work into U.S. federal careers. It combines job search with plain-language explanations of federal hiring and CV-to-job comparisons.
Key features
- 01Search USAJOBS openings with filters
- 02Retrieve and compare job postings
- 03Explain federal grades, pay, and hiring
- 04Calculate GS salary with locality pay
- 05Save and assess a CV against jobs
- 06Extract KSA requirements
Use cases
- 01Find federal vacancies by role and location
- 02Understand grades, clearances, and hiring paths
- 03Compare a CV with a specific announcement
- 04Estimate pay for a GS grade and location
MCP support
Exposes tools for USAJOBS searches, job details, salary calculations, federal-concept explanations, and CV analysis to MCP clients. CV data is saved locally, while searches and analysis may send data to USAJOBS or the connected AI provider.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
npx -y federal-compass-mcpUSAJOBS_API_KEYSecretAPI key from developer.usajobs.govUSAJOBS_EMAILEmail used when requesting the API keyLocal servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.
Details
From the project READMEfederal-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
- Supports CV analysis by providing your CV and job requirements to your AI assistant for comparison
- 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 — 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):
{
"mcpServers": {
"federal-compass": {
"command": "npx",
"args": ["-y", "federal-compass-mcp@latest"],
"env": {
"USAJOBS_API_KEY": "your_api_key",
"USAJOBS_EMAIL": "[email protected]"
}
}
}
}
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 and privacy
Your saved CV is stored locally on your machine:
~/.federal-compass/
cv.json
codelists/ <- cached USAJobs reference data
The get_cv and check_qualification tools return your CV text to your MCP client. Depending on your client and its configuration, that text may be sent to an AI provider for processing. Review your client's and provider's privacy settings before sharing personal information.
The find_matching_jobs tool sends keywords extracted from your CV to USAJOBS to search for relevant vacancies.
Data source and independent analysis
Federal job announcements and API reference data come from USAJOBS. Use of the API is subject to the USAJOBS API Terms of Service. Each user should register for and use their own API credentials.
This is an independent project. It is not operated, sponsored, approved, or endorsed by the U.S. Office of Personnel Management (OPM) or USAJOBS.
AI explanations, CV comparisons, and extracted requirement matches are unofficial analysis, not an agency determination of eligibility. Verify requirements, deadlines, and application instructions against the current official announcement on USAJOBS before applying.
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.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.