Federal Compass MCP — Claude Code MCP server: what it does
Wires USAJobs into your AI agent so it can search federal openings, decode the legalese in postings and work out GS pay.
claude mcp add --env USAJOBS_API_KEY=<USAJOBS_API_KEY> --env USAJOBS_EMAIL=<USAJOBS_EMAIL> --transport stdio federal-compass-mcp -- npx -y federal-compass-mcpWhat Federal Compass MCP 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.
What it helps with
- 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 for the agent
- 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
How to install Federal Compass MCP
Platform CLI
claude mcp add --env USAJOBS_API_KEY=<USAJOBS_API_KEY> --env USAJOBS_EMAIL=<USAJOBS_EMAIL> --transport stdio federal-compass-mcp -- npx -y federal-compass-mcpReplace <…> with your own values
Platform CLI
codex mcp add federal-compass-mcp --env USAJOBS_API_KEY=<USAJOBS_API_KEY> --env USAJOBS_EMAIL=<USAJOBS_EMAIL> -- npx -y federal-compass-mcpReplace <…> with your own values
Config file
{
"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
Config file
{
"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
Platform CLI
gemini mcp add -e USAJOBS_API_KEY=<USAJOBS_API_KEY> -e USAJOBS_EMAIL=<USAJOBS_EMAIL> federal-compass-mcp npx -y federal-compass-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Federal Compass MCP
How do I install Federal Compass MCP in Claude Code?
Add the server with claude mcp add federal-compass-mcp -- npx -y federal-compass-mcp. Then run it again with credentials: `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`.
What does Federal Compass MCP do?
It searches USAJobs, rewrites postings in plain language, computes GS salary with locality pay and checks your CV against a job's requirements.
What do I need to run it?
Node.js 22+, a free USAJobs API key and any MCP client. The key and your email are read from environment variables.
