# USAJOBS (OPM) MCP > USAJOBS (OPM) MCP Server lets your AI agent access and analyze federal job postings directly from USAJOBS. Use `search_jobs` to find currently open roles by keyword, location, or category. Pull historical data with `get_historic_joas` for trend analysis, or use `get_code_list` to validate occupational series codes before running a search. ## Overview - **Category:** industry-titans - **Price:** Free - **Tags:** federal-jobs, career-search, public-sector, hiring-data, job-listings, government-employment ## Description Your AI client connects straight to the official USAJOBS database, giving your agent direct access to federal job postings and personnel data. You don't gotta leave your chat window to dig into the federal hiring ecosystem. When you’re ready to work, you first need to nail down your search parameters. Before running a main query, run `get_code_list` to pull a list of valid codes for occupational series, agency subelements, and pay plans. This step ensures your filters are precise; you won't waste time searching with bad data. Once you have those codes validated, you can use `search_jobs`. This tool lets you find currently open roles by filtering multiple criteria: keywords, specific geographic locations, job categories, or defined hiring paths like Veterans and students. It pulls live announcements for federal jobs on USAJOBS. To truly understand what a role entails, you need the full text. Use `get_announcement_text` to fetch the detailed, long-form text for any specific Job Announcement (JOA), whether it's current or historical. This gives you the complete picture—the summary, every required qualification, and the specific duties of the job. When you need big-picture data, look at trends over time. You can pull bulk records using `get_historic_joas`. This tool provides access to a massive dataset of past JOAs, making it perfect for deep trend analysis across different periods. Because this volume of data is huge, the tool supports pagination through continuation tokens, letting you grab entire datasets without running into limits. So, you use `get_code_list` first to validate your search codes; then you fire up `search_jobs` to find current openings. If you nail down a specific posting from those results, you run `get_announcement_text` to read the fine print. And if you're doing research on federal hiring patterns, `get_historic_joas` pulls all the necessary bulk data. ## Tools ### get_announcement_text Retrieves the full, long-form text details for any current or past job posting (JOA). ### get_code_list Returns a list of valid values and codes needed to correctly filter search results. ### get_historic_joas Pulls bulk data of past job announcements, supporting pagination via continuation tokens for large datasets. ### search_jobs Searches for currently open federal jobs on USAJOBS using filters like keyword, location, and category. ## Prompt Examples **Prompt:** ``` Search for active Software Engineer jobs in Washington, DC with a minimum salary of $100,000. ``` **Response:** ``` I found 12 active Software Engineer positions in Washington, DC meeting your criteria. Notable listings include a Lead Developer role at the Department of State and a Senior Engineer position at NASA. Would you like the details for any of these? ``` **Prompt:** ``` Get the full duties and qualifications for announcement number 784521900. ``` **Response:** ``` Retrieving announcement text... For JOA 784521900, the primary duties involve managing cloud infrastructure and ensuring cybersecurity compliance. Qualifications require at least one year of specialized experience at the GS-12 level. Shall I summarize the full text for you? ``` **Prompt:** ``` List the occupational series codes for Information Technology positions. ``` **Response:** ``` I've fetched the code list. For Information Technology, the primary series is 2210. Other related codes include 1550 (Computer Science) and 0854 (Computer Engineering). ``` ## Capabilities ### Search Active Job Listings Find currently open federal roles by filtering criteria like keywords, location, or job category using `search_jobs`. ### Retrieve Full Posting Text Fetch the detailed text for a specific job announcement, including full summaries and qualification requirements, with `get_announcement_text`. ### Analyze Historical Job Trends Pull bulk data of past and present JOAs using `get_historic_joas`, allowing for trend analysis across time periods. ### Validate Federal Codes Get a list of valid codes—like occupational series or pay plan IDs—needed to refine search filters precisely with `get_code_list`. ## Use Cases ### Finding a Role Match A job seeker needs to find active Software Engineer roles near Boston. Instead of typing complex filters on the USAJOBS site, they ask their agent to `search_jobs` with 'Software Engineer' and 'Boston'. The agent returns 15 current listings instantly. ### Researching Career Paths A counselor wants to show a client the typical requirements for an IT role. They first use `get_code_list` to validate the series code, then run `search_jobs`, and finally pass the resulting Job ID to `get_announcement_text` to get the full duties list. ### Analyzing Department Spending A data analyst needs to know the volume of hiring for specific departments over five years. They use `get_historic_joas` repeatedly, calling it with continuation tokens until all available records are retrieved for their analysis. ### Verifying Data Integrity A power user wants to ensure they are searching using the most current classification system. Before running `search_jobs`, they call `get_code_list` just to validate that the pay plan codes and occupational series IDs haven't changed. ## Benefits - Finding Jobs: Use `search_jobs` to quickly filter live, active listings by keywords and location. You bypass the complicated manual search forms entirely. - Deep Dive Analysis: When you find a promising role, use `get_announcement_text`. It pulls the full job description—duties, qualifications, everything—in one shot. - Historical Trends: Need to see how many jobs were posted for 'Data Analyst' in 2018 vs. 2023? Run `get_historic_joas` and analyze the raw data without manual scraping. - Precise Filtering: Don't guess at codes. Call `get_code_list` first. It gives you valid occupational series and pay plan IDs, making your searches accurate every time. - Time Savings: Instead of jumping between USAJOBS search pages and documentation guides, your agent handles the whole process in natural conversation. ## How It Works The bottom line is: You configure your access credentials once, then let your AI client run specific tools to get structured data from federal records. 1. Subscribe to the USAJOBS (OPM) MCP Server and provide your required USAJOBS API Key and User Agent email. 2. Direct your AI agent to run `get_code_list` first. This retrieves valid codes for filtering searches, ensuring you don't use outdated parameters. 3. Use `search_jobs`, supplying the validated code list alongside keywords and locations. The agent returns a filtered list of live job announcements. ## Frequently Asked Questions **How do I search for jobs using the USAJOBS (OPM) MCP Server?** Run `search_jobs`. This tool lets your agent filter live job announcements by keywords, location, and category. It's the main entry point for finding active roles. **What is the difference between `get_announcement_text` and `search_jobs`?** `search_jobs` gives you a list of *titles* and brief summaries from currently open jobs. You must use `get_announcement_text` to get the full, detailed text for any specific job ID. **Can I analyze old federal hiring data with USAJOBS (OPM) MCP Server?** Yes. Use `get_historic_joas`. This tool retrieves bulk records of past Job Announcements, allowing you to study trends over time. **Do I need to use `get_code_list` before running a search?** It's best practice. Running `get_code_list` first validates the specific codes (like pay plans) you plan to use, ensuring your search criteria are accurate and current. **How do I use `get_code_list` to refine my search criteria?** You run `get_code_list` first, which retrieves valid codes and values for filtering results. This gives you the specific occupational series or pay plan IDs needed to make your `search_jobs` query highly targeted. **What is the difference between using `get_historic_joas` and `get_announcement_text`?** `get_historic_joas` pulls bulk data for many past job announcements, supporting pagination via a continuation token. You use `get_announcement_text` when you need the full text of one specific JOA ID. **Does this server handle rate limits or throttling during large data retrievals?** The connection handles standard API rate limiting, but for bulk historical analysis using `get_historic_joas`, you should implement backoff logic. The tool documentation provides specific guidelines on managing call frequency. **What information does the USAJOBS (OPM) MCP Server require to connect and authenticate?** You must provide a valid USAJOBS API Key and your User Agent, which is typically an email address. These credentials authorize access to the live federal hiring database. **How can I filter jobs by a specific location and salary range?** Use the `search_jobs` tool. You can provide parameters like `LocationName` (e.g., 'Washington, DC') and `RemunerationMinimumAmount` to narrow down the results to your specific needs. **Where can I find the full description of duties for a job posting?** The `get_announcement_text` tool is designed specifically for this. By providing the announcement number, the agent will retrieve the full text for Summary, Duties, and Qualifications. **How do I know which codes to use for occupational series like IT or Engineering?** You can use the `get_code_list` tool with the endpoint 'occupationalseries'. This will return a list of all valid codes and their corresponding titles (e.g., 2210 for Information Technology).