visa-jobs-mcp

visa-jobs-mcp is an MCP server that helps agents find relevant jobs from fresh LinkedIn searches, with optional visa-aware filtering.

<img width="775" height="663" alt="Screenshot 2026-02-20 at 10 20 22 am" src="https://github.com/user-attachments/assets/91dd3b16-59eb-42d5-806a-155c8d7b985f" />

It is built for speed and practical outcomes:

• search jobs in a location,
• match employers against sponsorship history,
• return actionable results with links and contact info,
• keep user data local.

Get Started

1. Install on macOS (Homebrew)

brew tap neosh11/visa-jobs-mcp
brew install neosh11/visa-jobs-mcp/visa-jobs-mcp

2. Install on macOS/Linux (bash installer)

curl -fsSL https://raw.githubusercontent.com/neosh11/visa-jobs-mcp/main/scripts/install.sh | bash

Pin a specific version:

curl -fsSL https://raw.githubusercontent.com/neosh11/visa-jobs-mcp/main/scripts/install.sh | bash -s -- --version 0.3.1

3. Install on Windows (PowerShell installer)

irm https://raw.githubusercontent.com/neosh11/visa-jobs-mcp/main/scripts/install.ps1 | iex

Pin a specific version:

$env:VISA_JOBS_MCP_VERSION = "0.3.1"
irm https://raw.githubusercontent.com/neosh11/visa-jobs-mcp/main/scripts/install.ps1 | iex

4. Register in Codex (macOS/Linux)

codex mcp add visa-jobs-mcp --env VISA_JOB_SITES=linkedin -- visa-jobs-mcp

Register in Codex (Windows PowerShell):

codex mcp add visa-jobs-mcp --env VISA_JOB_SITES=linkedin -- "$env:LOCALAPPDATA\\Programs\\visa-jobs-mcp\\bin\\visa-jobs-mcp.exe"

Verify:

codex mcp list
codex mcp get visa-jobs-mcp

5. Use it in chat

In a new Codex session, ask naturally:

• Find IT jobs in Delhi for my skills.
• Set my visa preference to E3 and find software engineer jobs in New York that sponsor E3.

Build from source (optional)

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

If you need to refresh data/companies.csv from source, run:

./scripts/run_internal_pipeline.sh

Note: MCP runtime is Go-only. Python is only needed for maintainers running the internal dataset pipeline.

Live LinkedIn E2E (manual)

Run a real end-to-end search against LinkedIn (not stubbed tests):

./scripts/run_live_linkedin_e2e.sh

Optional timeout override:

VISA_E2E_TEST_TIMEOUT=8m ./scripts/run_live_linkedin_e2e.sh

Optional live test parameters:

VISA_E2E_VISA_TYPE=E3 \
VISA_E2E_LOCATION="New York, NY" \
VISA_E2E_JOB_TITLE="Software Engineer" \
./scripts/run_live_linkedin_e2e.sh

What It Supports

• LinkedIn-only search.
• General skill/location job search with no visa setup required.
• Optional visa preference matching when preferred_visa_types is set.
• Search sessions with pagination and resume support.
• Saved jobs and ignored jobs.
• Employer contact extraction when available.
• Local-first private data storage.
• No proxy usage.
• No LLM calls inside MCP runtime (agent handles reasoning).

Core MCP Tools

• start_job_search
• get_job_search_status
• get_job_search_results
• set_user_preferences
• start_visa_job_search
• get_visa_job_search_status
• get_visa_job_search_results
• save_job_for_later
• ignore_job
• list_saved_jobs
• list_ignored_jobs
• get_mcp_capabilities

Tip: ask the agent to call get_mcp_capabilities first for a machine-readable contract.

MCP Contract (Generated)

<!-- MCP_CONTRACT:START --> <details> <summary><strong>Expand MCP Contract</strong> (auto-generated)</summary>

Generated from get_mcp_capabilities() via scripts/generate_contract_docs.py.

Server

• server: visa-jobs-mcp
• version: 0.3.1
• capabilities_schema_version: 1.2.0
• confidence_model_version: v1.1.0-rules-go

Required Before Search

• tool: start_job_search
• required_fields: user_id

Design Decisions

• agent_is_reasoning_layer: True
• background_search_runs_local_persistence: True
• data_not_shared_or_sold: True
• first_class_job_management: True
• free_forever: True
• fresh_job_search_per_query: True
• ignored_companies_local_persistence: True
• ignored_jobs_local_persistence: True
• license: MIT
• llm_api_keys_required_by_mcp: False
• llm_runtime_inside_mcp: False
• no_fake_reviews_or_bot_marketing: True
• proxies_used: False
• rate_limit_backoff_retries: True
• saved_jobs_local_persistence: True
• search_sessions_local_persistence: True
• strict_user_visa_match: False
• strictness_modes_supported: ['balanced', 'strict']
• supported_job_sites: ['linkedin']
• visa_matching_optional: True

Defaults

• dataset_stale_after_days: 30
• job_db_path: data/app/visa_jobs.db
• max_scan_results: 1200
• max_search_sessions_per_user: 20
• rate_limit_initial_backoff_seconds: 2
• rate_limit_max_backoff_seconds: 30
• rate_limit_retry_window_seconds: 180
• scan_multiplier: 8
• search_run_ttl_seconds: 21600
• search_session_ttl_seconds: 21600
• strictness_mode: strict
• tool_call_soft_timeout_seconds: 48

Tools

| Tool | Description | Required Inputs | Optional Inputs | |---|---|---|---| | get_mcp_capabilities | Return MCP capabilities, tools, and contracts for agent self-discovery. | - | - | | set_user_preferences | Save the user's visa preferences for optional visa-specific matching. | user_id, preferred_visa_types | - | | set_user_constraints | Save urgency and work-mode constraints used for personalized guidance. | user_id | - | | get_user_preferences | Fetch the saved user preferences and constraints. | user_id | - | | get_user_readiness | Report whether the user and local dataset are ready for search. | user_id | - | | find_related_titles | Return adjacent role titles to widen low-yield searches. | job_title | - | | add_user_memory_line | Append a profile memory line (skills, goals, fears, constraints). | user_id, content | - | | query_user_memory_blob | Query the user's local memory blob with optional text filtering. | user_id | - | | delete_user_memory_line | Delete one memory line by id from the local blob. | user_id, line_id | - | | save_job_for_later | Save a job to the user's local shortlist for follow-up. | user_id | job_url, result_id, session_id | | list_saved_jobs | List saved jobs in reverse-chronological order. | user_id | - | | delete_saved_job | Remove one saved job from the local shortlist. | user_id, saved_job_id | - | | ignore_job | Hide one job from future results for this user. | user_id | job_url, result_id, session_id | | list_ignored_jobs | List ignored jobs in reverse-chronological order. | user_id | - | | unignore_job | Unhide a previously ignored job by id. | user_id, ignored_job_id | - | | ignore_company | Hide all jobs from a company in future searches. | user_id | - | | list_ignored_companies | List ignored companies in reverse-chronological order. | user_id | - | | unignore_company | Remove one company from the ignored list. | user_id, ignored_company_id | - | | mark_job_applied | Mark a job as applied and persist pipeline state. | user_id | - | | update_job_stage | Update lifecycle stage for a tracked job (saved/applied/interview/etc). | user_id, stage | - | | list_jobs_by_stage | List tracked jobs filtered by lifecycle stage. | user_id, stage | - | | add_job_note | Attach or append a note to a tracked job record. | user_id, note | - | | list_recent_job_events | List recent stage transitions and lifecycle events. | user_id | - | | get_job_pipeline_summary | Summarize tracked pipeline counts by stage for one user. | user_id | - | | clear_search_session | Delete one cached search session or all sessions for a user. | user_id | - | | export_user_data | Export all local records for a user across stores. | user_id | - | | delete_user_data | Permanently delete all local records for a user. | user_id, confirm | - | | get_best_contact_strategy | Suggest best outreach channel/contact for a job. | user_id | - | | generate_outreach_message | Generate a practical outreach draft tailored to user and role. | user_id | - | | start_job_search | Start a background job search without requiring visa preferences. | location, job_title, user_id | - | | get_job_search_status | Poll incremental progress/events for a background job search run. | user_id, run_id | - | | get_job_search_results | Fetch current result page from a background job search run. | user_id, run_id | - | | cancel_job_search | Request cancellation of an in-progress background job search run. | user_id, run_id | - | | start_visa_job_search | Start a background search run for long scans. | location, job_title, user_id | - | | get_visa_job_search_status | Poll incremental progress/events for a background search run. | user_id, run_id | - | | get_visa_job_search_results | Fetch current result page from a background search run. | user_id, run_id | - | | cancel_visa_job_search | Request cancellation of an in-progress background run. | user_id, run_id | - | | discover_latest_dol_disclosure_urls | Discover latest DOL LCA/PERM disclosure sources. | - | - | | run_internal_dol_pipeline | Run internal pipeline to refresh sponsor-company dataset. | - | - | | refresh_company_dataset_cache | Clear and reload in-memory company dataset cache. | - | - |

Search Response Fields

• run
• status
• stats
• guidance
• dataset_freshness
• pagination
• recovery_suggestions
• jobs[].result_id
• jobs[].job_url
• jobs[].title
• jobs[].company
• jobs[].location
• jobs[].site
• jobs[].date_posted
• jobs[].description_fetched
• jobs[].description
• jobs[].description_excerpt
• jobs[].salary_text
• jobs[].salary_currency
• jobs[].salary_interval
• jobs[].salary_min_amount
• jobs[].salary_max_amount
• jobs[].salary_source
• jobs[].job_type
• jobs[].job_level
• jobs[].company_industry
• jobs[].job_function
• jobs[].job_url_direct
• jobs[].is_remote
• jobs[].employer_contacts
• jobs[].visa_counts
• jobs[].visas_sponsored
• jobs[].visa_match_strength
• jobs[].eligibility_reasons
• jobs[].confidence_score
• jobs[].confidence_model_version
• jobs[].agent_guidance

Paths

• dataset_default: data/companies.csv
• ignored_companies_default: data/config/ignored_companies.json
• ignored_jobs_default: data/config/ignored_jobs.json
• job_management_db_default: data/app/visa_jobs.db
• pipeline_manifest_default: data/pipeline/last_run.json
• saved_jobs_default: data/config/saved_jobs.json
• search_runs_store_default: data/config/search_runs.json
• search_session_store_default: data/config/search_sessions.json
• user_memory_blob_default: data/config/user_memory_blob.json
• user_preferences_default: data/config/user_preferences.json

Deprecations

• build_company_dataset_from_dol_disclosures -> run_internal_dol_pipeline (soft_deprecated)

<details> <summary>Raw Capabilities JSON</summary>

{
  "capabilities_schema_version": "1.2.0",
  "confidence_model_version": "v1.1.0-rules-go",
  "defaults": {
    "dataset_stale_after_days": 30,
    "job_db_path": "data/app/visa_jobs.db",
    "max_scan_results": 1200,
    "max_search_sessions_per_user": 20,
    "rate_limit_initial_backoff_seconds": 2,
    "rate_limit_max_backoff_seconds": 30,
    "rate_limit_retry_window_seconds": 180,
    "scan_multiplier": 8,
    "search_run_ttl_seconds": 21600,