Skip to main content
Glama
federal-compass-mcp

federal-compass-mcp

by skivuha

federal-compass-mcp

Your AI compass from private sector to federal career

npm version CI License: MIT MCP OpenSSF Scorecard

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

Available Tools

10 tools
calculate_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

    A4.1/5.0

    Scored across 10 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      An 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.
      1
      4
      -
    • F
      license
      B
      quality
      C
      maintenance
      An MCP server for interacting with the USAspending.gov API, supporting local use with Claude Desktop and cloud deployment with login.gov authentication.
      3
      10
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      A local MCP server that connects the Globick activities API to Claude Desktop, enabling natural language search and filtering of the activities catalogue.
      -