io.github.foundrole/jobs-mcp-proxy

Official15 tools

by foundrole · TypeScript

FoundRole — AI Job Search & Application Tracker MCP for Claude & ChatGPT

MCP server for AI job search — find jobs, track applications, get alerts. Claude, ChatGPT, Cursor.

Search jobs, track applications, and receive alerts across multiple AI assistant platforms.

Topics

ai-assistantapplication-trackercareerchatgptclaudecursorjob-alertsjob-boardjob-huntingjob-searchjob-trackerjobsmcpmcp-proxymcp-servermodel-context-protocoloauthperplexitywindsurffoundrole

Captured live from the server via tools/list.

job_alert_list

Lists the authenticated user's job alerts across all subscription sources (regular, company page, MCP). **Input:** - `status`: Filter by status — one of pending, active, unsubscribed (optional, default: all statuses) - `limit`: Number of results to return (default 20, max 50) - `offset`: Number of results to skip (default 0) **Output:** Returns the user's job alerts with pagination info and a summary of the underlying job search (query, location, company where available). Each response includes a system_instruction describing how to present the results for the current client.

Parameters (3)

statusstring
Filter by status: pending, active, unsubscribed
limitinteger
Number of results to return (default 20, max 50)
offsetinteger
Number of results to skip (default 0)

job_alert_subscribe

Subscribes the authenticated user to job alerts for a specific saved job search. **Input:** - `job_search_id`: The job search identifier to subscribe to (required). Accepts either the job search UUID or the composite job ID returned by `jobs_search` / `jobs_details` (format: "seo_id--job_search_id"). - `frequency`: Alert frequency — one of daily, weekly, monthly (optional, defaults to "weekly") **Output:** Returns the created or updated job alert with id, status, and frequency. Idempotent: calling this tool for an already-subscribed search updates the existing alert without creating a duplicate.

Parameters (2)

job_search_idstringrequired
Job search UUID or composite job id ("seo_id--job_search_id") from jobs_search results
frequencystring
Alert frequency: daily, weekly, monthly (defaults to "weekly")

job_alert_unsubscribe_all

Unsubscribes the authenticated user from ALL of their job alerts at once, across every subscription source (regular, company page, MCP). **Input:** - `confirm`: Must be `true` to execute. The call is rejected when omitted or not true — this guards against an unintended bulk unsubscribe. **Output:** Confirms how many alerts were unsubscribed. Idempotent: returns success even when the user has no active alerts.

Parameters (1)

confirmbooleanrequired
Set to true to confirm unsubscribing from every alert; the call is rejected otherwise

job_alert_unsubscribe

Unsubscribes the authenticated user from job alerts for a specific job search. **Input:** - `job_search_id`: The job search identifier to unsubscribe from (required). Accepts either the job search UUID or the composite job ID returned by `jobs_search` / `jobs_details` (format: "seo_id--job_search_id"). **Output:** Confirms the alert has been unsubscribed. Idempotent: returns success even when the user was not subscribed or is already unsubscribed.

Parameters (1)

job_search_idstringrequired
Job search UUID or composite job id ("seo_id--job_search_id") from jobs_search results

jobs_details

Fetches full details for one job by the `id` returned from jobs_search — the deeper view behind a search result. **Input:** - `job_id`: The exact ID string from the `id` field of a `jobs_search` result. **Output:** Complete job details: description, skills, benefits, requirements, salary, and application link.

Parameters (1)

job_idstringrequired
The unique identifier of the job from jobs_search results

jobs_search

Searches a database for real-time job listings matching the user's criteria. The query is the full job title or role: "Ruby Developer" or "Ruby on Rails Engineer" rather than a bare keyword like "Ruby", which is too broad and matches unrelated fields. Results may be filtered by location, company, and how recently a job was posted. Each result carries an `id`; jobs_details takes that `id` and returns the job's full description, requirements, and benefits. The response also carries a `nextCursor` for the next page of results; a follow-up page is fetched by passing only that cursor, with no other search parameters. Each response includes a system_instruction describing how to present the results for the current client.

Parameters (5)

querystring
The full job title or skill (e.g., "Ruby Developer", NOT just "Ruby")
locationstring
Geographic location (e.g., 'Boston, MA')
companystring
The official company name
posted_days_agointeger
Number of days ago to search for jobs (1-365)
cursorstring
Pagination cursor. Treat as an opaque string. COPY EXACTLY.

reminder_delete

Deletes a reminder from a tracked job. **Input:** - `tracked_job_id`: The tracked job ID — `trackedJobs[].id` from tracker_list output, distinct from `trackable.id` and `job.id` (required) **Output:** Returns the updated tracked job with reminderAt cleared.

Parameters (1)

tracked_job_idstringrequired
The tracked job ID — `trackedJobs[].id` from tracker_list output, distinct from `trackable.id` and `job.id` (required)

reminder_list

Lists tracked jobs that have reminders set, ordered by reminder time (soonest first). **Input:** - `limit`: Number of results to return (default 20, max 50) **Output:** Returns a list of tracked jobs with active reminders.

Parameters (1)

limitinteger
Number of results to return (default 20, max 50)

reminder_set

Sets a reminder for a tracked job. Sends a confirmation email with .ics calendar attachment. **Input:** - `tracked_job_id`: The tracked job ID — `trackedJobs[].id` from tracker_list output, distinct from `trackable.id` and `job.id` (required) - `remind_at`: Reminder date/time in ISO 8601 format, e.g. "2025-03-15T10:00:00Z" (required, must be in the future) **Output:** Returns the updated tracked job with reminderAt field.

Parameters (2)

tracked_job_idstringrequired
The tracked job ID — `trackedJobs[].id` from tracker_list output, distinct from `trackable.id` and `job.id` (required)
remind_atstringrequired
ISO 8601 datetime, e.g. "2025-03-15T10:00:00Z" (must be in the future)

tracker_add_external

Saves a job posting found anywhere on the open web into the user's tracker. For jobs that came from jobs_search results, tracker_add (which takes a job_id) is the right tool instead. A job seen elsewhere in the conversation needs no prior jobs_search call — its URL and details from the conversation are sufficient input. `url`, `company_name`, `title_name`, `location_name`, and `description` identify the posting; the url is the posting's own page (a company homepage is not accepted) and the description is the posting's description as the source result provides it — a short summary from the result card is acceptable when no fuller text is available. The remaining structured fields describe the posting's salary, employment type, work-location type, education, and experience; each is optional and any that the posting states can be supplied. Skills, benefits, and bonuses are derived from the description and are not accepted as inputs. Fields: - `url`: the job posting's direct URL (required; not a company homepage) - `company_name`: company name - `title_name`: job title - `location_name`: location, e.g. "New York, NY" - `description`: the posting's description from the source result; a short summary is acceptable (required) - `salary_min_value` / `salary_max_value`: salary range bounds (numbers) - `salary_value`: a single salary figure when there is no range (number) - `salary_type`: one of year, month, week, day, hour - `employment_type`: array of full_time, part_time, contractor, temporary, intern, volunteer, per_diem, other - `work_location_type`: one of on_site, remote, hybrid - `education_requirements`: array of no_requirements, high_school, associate_degree, bachelor_degree, professional_certificate, postgraduate_degree - `experience_months`: minimum required experience in months (number) - `status`: initial tracking status (saved, applied, interviewing, offered, archived); defaults to "saved" - `sub_status`: sub-status within the main status - `notes`: notes about the job Returns the tracked job, or an error if it is already tracked.

Parameters (16)

urlstringrequired
The job posting URL
company_namestringrequired
Company name
title_namestringrequired
Job title
location_namestringrequired
Location text, e.g. "New York, NY"
descriptionstringrequired
The posting's description from the source result; a short summary is acceptable
salary_min_valuenumber
Salary range minimum
salary_max_valuenumber
Salary range maximum
salary_valuenumber
Single salary figure when there is no range
salary_typestring
One of: year, month, week, day, hour
employment_typearray
Array of: full_time, part_time, contractor, temporary, intern, volunteer, per_diem, other
work_location_typestring
One of: on_site, remote, hybrid
education_requirementsarray
Array of: no_requirements, high_school, associate_degree, bachelor_degree, professional_certificate, postgraduate_degree
experience_monthsnumber
Minimum required experience in months
statusstring
Initial tracking status: saved, applied, interviewing, offered, archived
sub_statusstring
Sub-status within the main status
notesstring
Notes about this job

tracker_add

Tracks a job from jobs_search results in the user's job tracker, identified by its job_id. For a job found elsewhere on the open web (with a URL but no jobs_search job_id), tracker_add_external is the right tool instead. Fields: - `job_id`: the job ID from jobs_search results (required) - `status`: initial status (saved, applied, interviewing, offered, archived); defaults to "saved" - `sub_status`: sub-status within the main status - `notes`: notes about the job Returns the tracked job with its details, or an error if it is already tracked. A job that was previously removed from the tracker is restored with its earlier status and notes.

Parameters (4)

job_idstringrequired
The job ID from jobs.search results
statusstring
Initial tracking status: saved, applied, interviewing, offered, archived
sub_statusstring
Sub-status within the main status
notesstring
Notes about this job

tracker_list

Lists the user's tracked jobs with optional filtering and pagination. **Input:** - `status`: Filter by status (saved, applied, interviewing, offered, archived) - `limit`: Number of results per page (default 20, max 50) - `offset`: Number of results to skip (default 0) **Output:** Returns a list of tracked jobs grouped by status with pagination info. Each response includes a system_instruction describing how to present the results for the current client.

Parameters (3)

statusstring
Filter by status: saved, applied, interviewing, offered, archived
limitinteger
Number of results per page (default 20, max 50)
offsetinteger
Number of results to skip (default 0)

tracker_remove

Removes a job from the user's job tracker. **Input:** - `tracked_job_id`: The tracked job ID — `trackedJobs[].id` from tracker_list output, distinct from `trackable.id` and `job.id` (required) **Output:** Confirms the job was removed from tracking.

Parameters (1)

tracked_job_idstringrequired
The tracked job ID — `trackedJobs[].id` from tracker_list output, distinct from `trackable.id` and `job.id` (required)

tracker_update_status

Updates the status of a tracked job. **Input:** - `tracked_job_id`: The tracked job ID — `trackedJobs[].id` from tracker_list output, distinct from `trackable.id` and `job.id` (required) - `status`: New status: saved, applied, interviewing, offered, archived (required) - `sub_status`: Sub-status within the main status (optional) **Output:** Returns the updated tracked job.

Parameters (3)

tracked_job_idstringrequired
The tracked job ID — `trackedJobs[].id` from tracker_list output, distinct from `trackable.id` and `job.id` (required)
statusstringrequired
New status: saved, applied, interviewing, offered, archived
sub_statusstring
Sub-status within the main status

tracker_update

Updates details of a tracked job (notes, deadline, salary, tags). **Input:** - `tracked_job_id`: The tracked job ID — `trackedJobs[].id` from tracker_list output, distinct from `trackable.id` and `job.id` (required) - `notes`: Updated notes - `deadline`: Deadline date (ISO 8601 format) - `salary_offered`: Salary amount - `salary_offered_type`: Salary type: year, month, week, day, hour - `tags`: Comma-separated tags (e.g., "remote,startup,tech") - `reminder_at`: Reminder date/time in ISO 8601 format, e.g. "2025-03-15T10:00:00Z" (must be in the future, or empty to clear) **Output:** Returns the updated tracked job.

Parameters (7)

tracked_job_idstringrequired
The tracked job ID — `trackedJobs[].id` from tracker_list output, distinct from `trackable.id` and `job.id` (required)
notesstring
Notes about this job
deadlinestring
Deadline date in ISO 8601 format
salary_offerednumber
Salary amount
salary_offered_typestring
Salary type: year, month, week, day, hour
tagsstring
Comma-separated tags (e.g., "remote,startup,tech")
reminder_atstring
ISO 8601 datetime, e.g. "2025-03-15T10:00:00Z" (must be in the future, or empty to clear)

Install

claude_desktop_config.json

{
  "mcpServers": {
    "jobs-mcp-proxy": {
      "command": "npx",
      "args": [
        "-y",
        "@foundrole/ai-job-search-mcp@1.1.9"
      ]
    }
  }
}