visa-jobs

visa-jobs-mcp is a fast MCP server that helps agents find relevant visa-sponsored job opportunities by performing LinkedIn-style searches with optional visa-aware filtering. It supports a private, local data store and offers a set of built-in tools for managing searches, user preferences, and saved results. Core capabilities include starting a job search, checking status, retrieving results, and saving or ignoring individual jobs. When visa matching is enabled, the server can filter results to align with the user’s visa preferences, while still supporting generic job searches that do not require visa details.

To use the server effectively, start a search session with start_job_search or, if you want visa-aware results, start_visa_job_search. You can monitor progress with get_job_search_status or get_visa_job_search_status and fetch results with get_job_search_results or get_visa_job_search_results. Personalize results by calling set_user_preferences (for visa types) before running searches. You can also manage your shortlist by saving jobs for later with save_job_for_later or prune results by ignoring jobs or entire companies. For long-running or multi-session tasks, leverage the local persistence features (search_sessions_local_persistence, saved_jobs_local_persistence, ignored_jobs_local_persistence, etc.). A capabilities query via get_mcp_capabilities is recommended at the start of a session to discover available tools and contract details in a machine-readable form.

Prerequisites:

• Go toolchain installed (Go 1.18+)
• Basic shell (bash, PowerShell, zsh)

1. Install Go if not present:

   • macOS: brew install go
   • Windows: download from golang.org and run the installer
   • Linux: sudo apt-get install golang-go

2. Install the MCP server binary from source (example):

   • git clone https://github.com/neosh11/visa-jobs-mcp.git
   • cd visa-jobs-mcp
   • go mod download

3. Build the server binary locally (optional for quick test):

   • go build -o visa-jobs-mcp ./cmd/visa-jobs-mcp
   • ./visa-jobs-mcp --version

4. Run the server directly (development mode):

   • ./visa-jobs-mcp

5. Optional: Pin a specific version via Codex registration or scripts as shown in the README (VISA_JOBS_MCP_VERSION environment variable).

Notes:

• MCP runtime is Go-based; Python is only needed for internal data processing if you modify the dataset pipeline.
• If you prefer a Docker-based setup, you can wrap the Go binary in a container once you have a built artifact.

Environment variables to be aware of:

• VISA_JOB_SITES: restricts search sites (e.g., linkedin). If unset, defaults to linkedin.
• VISA_JOBS_MCP_VERSION: can pin to a specific release when used with Codex installation flow.

Common issues and tips:

• If you encounter network or LinkedIn-related throttling, ensure the runtime has network access and consider using saved job data persistence to reduce repeated fetches.
• Use get_mcp_capabilities first to understand available tools and required inputs for subsequent calls.
• Ensure local data directories (e.g., data/app/visa_jobs.db) are writable by the MCP process.