federal-compass-mcp
Connects AI to USAJobs to search, analyze, and explain federal jobs and career concepts.
Search federal job openings with optional filters (keyword, location, salary, grade, agency, remote, clearance, hiring path, who may apply).
Get full details for a specific job posting.
Compare 2-5 job postings side by side.
Save and retrieve your CV locally for automatic use.
Find jobs matching your CV by extracting skills and searching USAJobs.
Check your qualification against a specific job posting.
Extract KSA requirements from a job posting, optionally matching against your CV.
Explain federal concepts like GS grades, clearances, hiring paths, and pay plans.
Calculate GS salary with locality pay for a grade, step, and location.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@federal-compass-mcp Find me senior software developer jobs in Raleigh, NC"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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
Related MCP server: USA Spending MCP Server
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": "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, NCWhat 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 federal job openings. All filters optional — keyword, location, salary, grade, agency, remote |
| Get full details for a specific job posting |
| Compare 2-5 job postings side by side |
| Save your CV locally for automatic use in analysis |
| Read your saved CV |
| Explain GS grades, clearances, hiring paths, pay plans |
| Calculate GS salary with locality pay for any grade, step, and location |
| Find jobs matching your CV — extracts skills and searches USAJobs |
| Compare your CV against a specific job posting |
| 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 dataThe 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.
Available Tools
10 toolscalculate_salaryA
Calculate federal GS salary with locality pay adjustment. Returns base pay plus locality-adjusted pay for a specific grade, step, and location. Covers all 15 GS grades and ~58 locality pay areas.
Inputs: grade (required), step, location.
check_qualificationA
Compare your saved CV against a specific job posting. Returns your CV and the job requirements side by side for analysis. Requires a saved CV.
Inputs: job_id (required).
compare_jobsA
Compare 2-5 federal job postings side by side. Returns salary, grade, clearance, location, and more for each job. Makes one API call per job.
Inputs: job_ids (required), include_details.
explain_federal_conceptA
Explain federal career concepts in plain language: GS grades, security clearances, hiring paths, pay plans, and more.
Inputs: concept (required).
extract_ksaA
Extract KSA (Knowledge, Skills, Abilities) requirements from a federal job posting. Categorizes requirements by type (knowledge, skill, ability, experience, education, certification, other) and optionally matches them against your saved CV.
Inputs: job_id (required).
find_matching_jobsA
Find federal jobs that match your saved CV. Extracts skills and keywords from your CV and searches USAJobs. Requires a saved CV.
Inputs: results_per_page.
get_cvA
Read your saved CV. Returns the CV text and metadata (when it was saved, original format).
Inputs: no named parameters.
get_job_detailsA
Get full details for a specific federal job posting including duties, qualifications, and how to apply.
Inputs: job_id (required).
save_cvA
Save your CV text locally for automatic use in job matching and qualification checks. The CV is stored only on your machine.
Inputs: content (required), format.
search_jobsA
Search federal job openings on USAJobs. All parameters are optional. Returns job listings with title, agency, salary, location, and apply URL.
Inputs: grade, agency, remote, keyword, +6 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool has a clearly distinct purpose: salary calculation, CV management, job search, comparison, qualification checking, KSA extraction, and concept explanation. No two tools do the same thing, and even related tools like 'check_qualification' and 'extract_ksa' serve different functions.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., calculate_salary, save_cv, search_jobs). The verbs are specific and accurately describe the action, making the set predictable and easy to navigate.
With 10 tools, the server is well-scoped for its purpose of federal career assistance. Each tool addresses a specific need without redundancy or unnecessary complexity, covering salary, CV, job search, comparison, and qualification tasks.
The tool set covers core federal career tasks thoroughly: CV management (save, get), job search and details, salary calculation, qualification checks, and concept explanations. Minor gaps exist, such as the absence of tools for updating or deleting a CV, but these are not critical for basic workflow.
Maintenance
Related MCP Connectors
Public MCP server for discovering open jobs. Search, filter, and get application links.
MCP server for the GovContractScout US government contracts API: search, NAICS, match scoring.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Related MCP Servers
- FlicenseAqualityDmaintenanceAn MCP server that enables searching for jobs across Australian platforms (Seek and LinkedIn) from Claude or any MCP-compatible client, with filters for location, salary, employment type, and more.14-

USA Spending MCP Serverofficial
FlicenseBqualityCmaintenanceAn MCP server for interacting with the USAspending.gov API, supporting local use with Claude Desktop and cloud deployment with login.gov authentication.310-- FlicenseNot gradedqualityCmaintenanceA local MCP server that connects the Globick activities API to Claude Desktop, enabling natural language search and filtering of the activities catalogue.-
- AlicenseAqualityBmaintenanceLocal MCP server that manages a job search using Markdown files, enabling skills tracking, gap analysis, and offer pipeline management via Claude.866 npmMIT