Pydoll MCP Server for Job Search and Applications

MCP server for job search and job application workflows built on the Pydoll library.

The primary workflow is: discover a job, inspect its opportunity page, prepare the application, review the result, submit only with explicit authorization, and preserve evidence. LinkedIn has specialized search and Easy Apply tools. External ATS portals use the same semantic navigation and form workflow without requiring the agent to know DOM, frame, or open shadow-DOM paths.

The project still contains a complete browser automation catalog for explicit compatibility use through the full profile. Generic browsing is not the default product objective.

Status

Beta preview (v0.4.0b1). HTTP on 127.0.0.1 is the primary transport. stdio transport is available as an option (--transport stdio).

Endpoints:

• /health - Health check (no auth)

• /mcp - Streamable HTTP MCP (bearer token required)

• /sse - Server-Sent Events (bearer token required)

Related MCP server: DrissionPage MCP Server

Requirements

• Python >=3.10

• Chrome or Chromium installed

• Pydoll >=2.23.0

Windows native picker fallback is optional. Install the windows extra when a portal uses the File System Access API and the browser must control its native file dialog:

python -m pip install "pydoll-mcp-server[windows]"

Contributors must follow the quality gates and engineering conventions in docs/development.md.

Installation

python -m pip install -e ".[dev]"

For release distribution:

pip install pydoll-mcp-server

Running

Set a token before starting:

# Windows (PowerShell)
$env:PYDOLL_MCP_AUTH_TOKEN = python -c "import secrets; print(secrets.token_urlsafe(32))"

# Linux / macOS
export PYDOLL_MCP_AUTH_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"

These commands use Python instead of shell or .NET cryptography APIs, so token generation behaves consistently across Windows PowerShell 5.1, PowerShell 7, Linux, and macOS. Keep the generated value available when configuring MCP client headers. Generate a new token whenever the server is restarted with a new client configuration.

Start the server (HTTP, the default):

python -m pydoll_mcp_server.cli --host 127.0.0.1 --port 8765

Or via stdio:

python -m pydoll_mcp_server.cli --transport stdio

Curated tool profiles

The default profile is focused on job search and applications:

• jobs exposes 90 focused tools for lifecycle, search, semantic navigation, forms, uploads, waits, evidence, security handoffs, and LinkedIn workflows.

• full exposes all 151 public tools for explicit compatibility with advanced network, JavaScript, deep traversal, diagnostics, and low-level fallbacks.

• agent remains a legacy 73-tool general browser profile.

• linkedin remains a legacy 89-tool profile combining agent and LinkedIn search and Easy Apply helpers.

Select a profile explicitly with the CLI:

python -m pydoll_mcp_server.cli --transport stdio --tool-profile jobs
python -m pydoll_mcp_server.cli --transport stdio --tool-profile full
python -m pydoll_mcp_server.cli --transport stdio --tool-profile linkedin

The same setting can be provided through PYDOLL_MCP_TOOL_PROFILE; an explicit --tool-profile argument takes precedence. New clients should use jobs for LinkedIn search, Easy Apply, and external ATS forms. Use full only when advanced compatibility tools are explicitly required. agent and linkedin remain available for existing clients but are legacy profiles. server_status reports the active profile, its lifecycle, the recommended profile, and the exposed tool count. Pass include_tool_names=true when an agent needs the exact names exposed by the running server. Capabilities are filtered dynamically to the selected profile. The jobs profile does not advertise JavaScript, raw network, storage, cookies, deep traversal, or low-level mouse operations.

The product boundary and supported handoffs are defined in docs/job-automation-scope.md.

The curated profiles establish preferred contracts without removing anything from full: page_snapshot is the initial observation, page_get_active_surface is preferred for focused dialogs and forms, element_fill is the standard single-field fill, form_fill_fields is the standard bulk fill, and specific wait tools are preferred over the generic page_wait. LinkedIn workflows should use the linkedin_easy_apply_* tools instead of rebuilding the flow from generic form actions. Final LinkedIn submission still requires confirm_submit=true.

Application hardening applies to the job workflow tools. Page observations cache client- and tab-scoped references with structural selectors, positional hints, fingerprints, bounds, labels, and frame or shadow paths. Mutating tools re-resolve those references while holding the tab lock, so a React-style rerender does not silently redirect an action to the first matching element. Ambiguous recovery returns AMBIGUOUS_ELEMENT with usable candidates.

Use mode="auto" for element_fill and form_fill_fields. It dispatches framework-compatible events first, validates the resulting state, and makes at most one real-keyboard fallback for an ordinary field. framework_safe, keyboard, and blur are available when a portal requires a deliberate mode; keyboard fallback is refused for CAPTCHA, OTP, payment, biometric, identity, and password controls. Click results separate mcp_action, page_effect, and site_diagnostics; clicked=true means only that an event was sent. A requested effect that is not observed returns NO_EFFECT with its evidence.

page_snapshot and page_get_active_surface report passive security_controls for visible CAPTCHA, 2FA or OTP, payment, biometric, and identity-verification signals. These controls are never automated. The agent must ask the user to complete them and then re-observe the page before continuing. Text returned through the MCP is normalized to Unicode NFC while comparison helpers ignore case and diacritics without changing the text sent back to the agent.

Endpoints:

• GET http://127.0.0.1:8765/health - public health check, no token

• POST http://127.0.0.1:8765/mcp/ - Streamable HTTP MCP, with bearer token

• GET http://127.0.0.1:8765/sse/ - SSE MCP, with bearer token

MCP clients must send:

Authorization: Bearer <PYDOLL_MCP_AUTH_TOKEN>

PYDOLL_MCP_ALLOW_NO_AUTH=true should only be used in isolated development.

Job workflow tools

The default jobs profile is designed for the complete application lifecycle:

1. Search LinkedIn with linkedin_jobs_search or navigate to an explicit ATS job page with page_goto.

2. Inspect the opportunity and active form with linkedin_job_snapshot, page_snapshot, and page_get_active_surface.

3. Use form_preflight and form_prepare with only confirmed candidate facts.

4. Use form_review to inspect blockers, security handoffs, selected choices, uploads, and evidence.

5. Use form_submit_after_review only with a valid review token and explicit authorization.

6. Classify the result with submission_wait_for_confirmation and preserve the returned evidence.

Open shadow DOM resolution is automatic in this profile. External ATS pages use the external_ats_multistep preset. CAPTCHA, 2FA, login, payment, identity, attestation, sensitive consent, and missing candidate data always produce a handoff instead of an automated bypass.

Full compatibility catalog

The following inventory describes the complete full profile. These tools remain available for explicit compatibility and diagnostics, but are not part of the default job-focused surface.

Health and diagnostics:

• health_check

• server_status

• diagnostics_snapshot

• trace_start, trace_stop, trace_get, trace_cleanup

Lifecycle:

• browser_launch (supports session_intent="user_authenticated" + site_hint)

• browser_list (accepts include_health=true for a live CDP probe)

• browser_close

• browser_attach

• tab_list

• tab_activate

• tab_close

• tab_recover

• tab_new, tab_duplicate, tab_health_check, tab_recreate

• dialog_list, dialog_handle, popup_prepare, popup_wait

• proxy_validate, proxy_get

Browser lifecycle contract:

• Keep one MCP server process and one stable client_id for a browser session.

• Call browser_list before browser_launch; launching an already-open profile reuses the existing browser.

• A profile can be owned by only one MCP process at a time. A second process receives RESOURCE_LOCKED.

• Use tab_new for additional pages. Do not call browser_launch to create another tab.

• The server reconciles tab state with Chrome before listing or mutating tabs. tab_list reports live counts and enforces a maximum of five tabs per browser.

• tab_close reports success only after Chrome confirms that the target disappeared. If a before-unload dialog is present, it returns DIALOG_PRESENT; inspect and handle the dialog before retrying.

• The server closes its managed browsers during HTTP, stdio, and graceful process shutdown.

• Persistent profiles keep login state after shutdown, but the Chrome process itself is not kept alive.

• After a server restart, use browser_attach(profile_id=...) to reconcile a live browser owned by the same client. If the lease or CDP endpoint cannot be validated, the tool returns a handoff instead of attaching by profile directory name alone.

• tab_close refuses to act on a stale tab inventory and blocks closing the only managed tab. A transport timeout leaves the registry entry marked close_pending=true until the target disappears.

browser_launch accepts an optional proxy_server using http, https, socks4, or socks5, plus an optional proxy_bypass_list. Proxy credentials may be embedded for Pydoll authentication, but MCP responses and browser listings expose only sanitized metadata without usernames or passwords. Proxy configuration is immutable after browser launch.

Navigation:

• page_goto

• page_reload

• page_back

• page_forward

• page_wait

• page_wait_for_url, page_wait_for_function

• page_wait_for_text, page_wait_text_gone, page_wait_for_selector, page_wait_for_network_idle

• page_scroll, page_scroll_to

Observation:

• page_get_text

• page_get_tree

• page_get_tree_deep

• page_get_interactive_summary

• page_get_active_surface

• page_screenshot

• page_snapshot, page_diff

• page_get_accessibility_tree, frame_list, frame_snapshot

• page_print_pdf

Elements:

• element_find

• element_find_deep

• element_click

• element_click_by_text, element_click_center, mouse_click

• element_find_by_text_candidates

• element_resolve_again

• element_type

• element_fill

• element_fill_and_verify, element_wait_value

• element_get_text

• element_get_attribute

• element_screenshot

• element_get_state, element_wait_for_state

• element_select_option, element_check, element_uncheck

• element_hover, element_scroll_into_view, keyboard_press

• semantic finders by role, text, label, placeholder, and test ID

• form_snapshot, form_errors

• form_preflight, form_prepare, form_review, form_submit_after_review

• application_domain_status

• combobox_get_options, select_get_options, combobox_type_and_select, combobox_select_option

JavaScript and advanced helpers:

• js_evaluate_readonly

• js_evaluate

• user_agent_set

• user_agent_get

• viewport_set

• viewport_get

• cookies_get

• cookies_set

• storage_get

• storage_set

• download_expect

• download_prepare, download_wait, download_list, download_get_info

• upload_files

• upload_files_from_trigger

• file_upload_state, artifact_get_paths, artifact_import, artifact_export, artifact_prepare_upload

• profile_list, profile_promote

• operation_cancel

• http_request

LinkedIn Easy Apply helpers:

• linkedin_jobs_search

• linkedin_jobs_search_results

• linkedin_jobs_page_snapshot

• linkedin_jobs_open_result

• linkedin_application_evidence

• linkedin_job_snapshot

• linkedin_easy_apply_open

• linkedin_easy_apply_close

• linkedin_easy_apply_snapshot

• linkedin_easy_apply_wait_ready

• linkedin_easy_apply_upload_resume

• linkedin_easy_apply_click_next

• linkedin_easy_apply_fill_questions

• linkedin_easy_apply_handle_save_prompt

• linkedin_easy_apply_submit

• linkedin_message_recruiter

The LinkedIn helpers are browser automation helpers only. They do not generate resumes, choose answers, or integrate with external application trackers. linkedin_jobs_search builds and opens LinkedIn Jobs search URLs with keyword, location, remote-work, Easy Apply, date posted, experience level, job type, geo ID, pagination, and sort filters, then returns compact job results from the current page. Search result helpers can open a visible result in the same tab, inspect the search list plus detail panel, and return compact application evidence for external trackers. linkedin_easy_apply_submit refuses to submit unless confirm_submit=true is provided and the current modal is a verified final submit step. The Easy Apply helpers support both visible dialogs and inline LinkedIn forms. linkedin_easy_apply_upload_resume accepts an explicit local file through its path parameter, uploads it with paths internally, and reports filename and toast verification separately from upload acceptance. A selected filename is also a valid upload confirmation when LinkedIn does not show a toast. It delegates native picker handling to the generic upload layer when no input[type="file"] is available, while preserving LinkedIn-specific snapshot and toast verification. linkedin_easy_apply_fill_questions accepts the recommended list of question_contains answer objects and also accepts a simple question-to-value map for compatibility with clients that cannot construct the list shape. linkedin_message_recruiter requires a confirmed submitted application and a caller-provided message. It only messages one unambiguous recruiter listed in the current job detail surface, never navigates to a profile, sends InMail, or retries an inconclusive send automatically.

Uploads use the local source policy by default. The agent supplies a concrete local file path and does not need to call artifact_import, copy the file into the runtime directory, or prepare an intermediate artifact. Set PYDOLL_MCP_UPLOAD_POLICY=restricted to restore runtime-directory and explicit allowlist validation for a more constrained deployment.

upload_files_from_trigger supports three strategies for portals such as Greenhouse, Lever, and Workable:

• auto first uses a direct input, then a CDP file chooser interception, and finally the Windows native picker when the browser is visible and owned.

• intercept never opts into the desktop fallback and returns a structured UNSUPPORTED result for a real File System Access picker.

• desktop forces the Windows native picker and accepts one explicit local file.

The Windows fallback requires pydoll-mcp-server[windows], a visible browser, and a dialog that can be associated with the browser process. Headless sessions return a structured unsupported result instead of opening or controlling a native window. Every source is validated as an explicit regular local file with a size limit before the trigger is clicked. For native pickers, the MCP stages the validated file in a user-controlled temporary directory when needed, preserves its original filename, waits for page confirmation, and removes the temporary copy. The staging directory can be overridden with PYDOLL_MCP_UPLOAD_STAGING_DIR.

element_find requires a CSS selector by default or an XPath expression when strategy="xpath". Use element_find_by_role, element_find_by_text, or element_find_by_label when the intent is semantic rather than selector-based. element_click_by_text prefers actionable ancestors for nested labels and returns the activation element in its chosen candidate metadata.

Network inspection:

• network_enable

• network_disable

• network_list

• network_get_request

• network_replay_request

• network_get_response

• network_summary, network_clear

• network_wait_for_request, network_wait_for_response

• websocket_list

• websocket_get

• websocket_frames_list

network_list is a compact, sanitized index. network_get_request returns the raw request details captured by Chromium, including request headers and payload, without redaction. network_get_response retrieves the response body separately. websocket_list, websocket_get, and websocket_frames_list expose Chromium Network.webSocket* events as first-class captures, including handshakes, sent frames, received frames, frame errors, close events, payload truncation metadata, and optional raw output. Raw request and WebSocket data can contain credentials and personal data. Do not log it automatically, and call network_clear after analysis when retention is unnecessary.

http_request performs a direct HTTP(S) request using the owning browser tab's current cookies, user agent, and supported HTTP(S) proxy. It is not subject to page CORS. Destinations are restricted to the tab hostname unless allow_cross_origin=true. network_replay_request replays a captured request through the same service and requires confirm_side_effects=true for POST, PUT, PATCH, and DELETE. Direct HTTP does not reproduce Chromium TLS fingerprinting, cache, service workers, or client certificates.

Authenticated direct HTTP

http_request is the equivalent of a browser-associated API request context. It sends HTTP outside page JavaScript while sharing the owning tab's current cookies, user agent, and supported HTTP(S) proxy. Cookies received through Set-Cookie are synchronized back to the browser.

Example JSON request:

{
  "client_id": "agent",
  "tab_id": "tab-123",
  "method": "POST",
  "url": "/api/profile",
  "headers": {
    "Accept": "application/json"
  },
  "json_value": {
    "name": "Example"
  },
  "timeout": 30,
  "max_response_bytes": 1048576
}

Supported payload modes are mutually exclusive:

• json_value for JSON;

• form_fields for ordered URL-encoded fields, including duplicate names;

• body for raw UTF-8 text;

• body_base64 for raw binary data.

Relative URLs resolve against the current tab URL. Absolute URLs are restricted to the same hostname unless allow_cross_origin=true. Every redirect is validated before it is followed. Response bodies are returned as text when the content type is textual and as base64 otherwise. Truncation, original size when known, and returned size are explicit.

Capture and replay workflow

A deterministic agent workflow is:

1. Call network_enable and network_clear.

2. Start network_wait_for_request with URL and method filters.

3. Trigger the browser action that submits the request.

4. Call network_get_request with the captured request ID.

5. Call network_get_response to retrieve the browser response body.

6. Optionally call network_replay_request to resend the captured request.

7. Call network_clear when raw data is no longer needed.

Replay uses the current browser cookies and preserves the captured method, URL, headers, and available payload. Headers controlled by the HTTP client, including Host, Cookie, and Content-Length, are recalculated and listed in omitted_headers. Mutating methods require explicit confirmation:

{
  "client_id": "agent",
  "tab_id": "tab-123",
  "request_id": "request-456",
  "confirm_side_effects": true
}

Replay rejects incomplete multipart captures and ambiguous multiple binary entries instead of reconstructing data that Chromium did not provide.

Console inspection:

• console_enable, console_disable, console_list

Agent-friendly model

page_get_tree returns a compact, limited tree by default. It prioritizes visible body content and hides head, script, meta, style, link, and invisible nodes unless include_head=true or include_invisible=true is set. Interactive nodes receive element_id, selector_hint, xpath_hint, actionable, and resolution_confidence. An agent can observe the tree and call element_click or element_fill directly with the element_id, without calling element_find first.

page_get_interactive_summary is the recommended first observation for modern frontend apps. It returns visible controls with roles, names, labels, nearby section context, bounding boxes, selector hints, enabled/editable state, and cached element_id values.

page_get_active_surface detects the current modal, dialog, form, or main content surface. It returns fields, compact actionable controls, structural containers, primary and secondary actions, progress indicators, visible validation errors, pending required fields, and structured evidence. Scope auto prefers visible modals and dialogs over page content. Large select option lists are summarized with counts; use select_get_options or combobox_get_options when an agent needs the option list.

Radio and checkbox questions are represented as radio_group or checkbox_group fields. Each option includes its own element_id, label, checked state, and disabled state. A required group appears once in pending_required while no option is selected. Dismissal actions such as Close and Cancel are never selected as primary_action.

Use form_select_choice(field_label, option_label) for radio and checkbox questions. It restricts matching to the identified question, uses associated labels when needed, and returns success only after verifying the selected state.

For job applications, prefer the v2 workflow: call form_preflight for a read-only inventory, form_prepare for planned fields, choices, comboboxes, uploads, and intermediate steps, then form_review before any final action. form_submit_after_review requires an unexpired, single-use review token, explicit authorization_mode, a matching client and tab, and a fresh review. It performs exactly one final click and classifies the observed result. A security challenge, attestation, legal declaration, sensitive consent, or missing candidate fact produces a handoff instead of an automated action.

The workflow tools use contract version 2 envelopes with operation_id, success, and semantic status. Use verified, ready_for_submission, blockers, handoff, outcome, and verification as the source of truth. Legacy fields such as confirmed, checked, selected, and mode_used remain compatibility aliases. form_fill_fields and page_click_primary_action remain available for lower-level multi-step flows. element_find_by_text_candidates resolves duplicate visible text before clicking, and element_resolve_again recovers stale element handles after page re-renders.

submission_wait_for_confirmation returns a typed outcome. A URL change, modal disappearance, or portal limit by itself is never confirmation.

For React-like forms and custom controls, prefer element_fill, element_fill_and_verify, combobox_type_and_select, element_click_by_text, and condition waits before using custom JavaScript. js_evaluate and js_evaluate_readonly return structured JSON values directly in value; clients should not parse value as a JSON string.

The semantic form workflow automatically resolves controls in open shadow DOM and uses deep traversal only when the compact surface cannot prove coverage. Agents normally do not need to call page_get_tree_deep or pass shadow paths. Use page_get_tree_deep explicitly for diagnostics or cross-frame inspection. It is more expensive, has its own timeout, and returns:

• frame_path

• shadow_path

• partial

• errors

• visibility and interaction metadata when available

The alpha covers simple iframes, same-origin nested iframes, and open shadow DOM. Closed shadow roots and complex cross-origin cases still require additional validation.

Security

• Bearer token is required by default.

• The default bind must remain 127.0.0.1.

• Free execute_cdp_cmd is not exposed.

• Operating system commands are not exposed.

• Arbitrary filesystem read or write is not exposed.

• Navigation to file:// is blocked completely. Serve local fixtures through loopback HTTP.

• Screenshots and downloads use controlled directories. Uploads accept one explicit local file by default, validate its type and size, and can be constrained with PYDOLL_MCP_UPLOAD_POLICY=restricted and explicit roots.

• Cookies and storage are redacted by default on read.

• Sensitive attributes such as tokens, passwords, and cookies are redacted.

• Logs must redact bearer tokens, cookies, authorization headers, and sensitive fields.

• Proxy credentials are never returned, logged, traced, or persisted. The effective proxy URL is held only in internal in-memory browser state when needed for authenticated direct HTTP.

• Raw network inspection, direct HTTP, and replay responses can contain credentials and personal data. Consumers must not log these tool results automatically.

• Direct HTTP is same-host by default, blocks credentials embedded in URLs, validates every redirect, and requires explicit cross-origin opt-in.

• Replaying POST, PUT, PATCH, or DELETE requires confirm_side_effects=true.

js_evaluate is a sensitive tool:

• Requires explicit tab_id.

• Uses a short timeout by default.

• Limits code and result size.

• Logs a summarized audit with hash, duration, and size.

• Must not log full code or full results.

• Warns or blocks dangerous patterns, depending on mode.

• May be disabled in the future via a safe-mode configuration.

js_evaluate_readonly is preferred for inspection, but should also be treated as sensitive.

Runtime directories

Runtime data is stored outside the repository by default:

• Windows: %LOCALAPPDATA%\pydoll-mcp-server

• macOS: ~/Library/Application Support/pydoll-mcp-server

• Linux: ~/.local/share/pydoll-mcp-server

Expected subdirectories:

• profiles/ (contains index.json with safe profile metadata)

• tmp/

• downloads/

• artifacts/

• logs/

Session continuity

Persistent browser profiles preserve cookies, localStorage, and login state across launches. Use session_intent="user_authenticated" with site_hint in browser_launch to pick up an existing profile matching a domain. profile_list discovers available profiles and profile_promote promotes a preserved temporary profile to persistent. Profiles are indexed safely in profiles/index.json without exposing cookies, tokens, storage values, or absolute paths.

Vendored Pydoll documentation

Vendored Pydoll documentation is available at:

references/pydoll-docs/

Do not mix vendored documentation with MCP server code.

Testing

Core gates:

python -m pytest -q
python -m ruff check .
python -m ruff format --check .
python -m mypy --strict src tests
python -m pyright
python -m pytest -m mcp_e2e -q
python -m pytest -m browser_smoke -q
python -m build

Useful test suites by area:

python -m pytest tests/contract -q
python -m pytest tests/unit/test_concurrency.py -q
python -m pytest tests/unit/test_security.py tests/unit/test_files_security.py -q
python -m pytest tests/p2/ -q

browser_smoke opens Chrome/Chromium headless and validates real flows with local fixtures.

Known limitations

• Console inspection depends on Chromium Runtime events and may return UNSUPPORTED when unavailable.

• browser_attach does not support reconnection across server sessions (returns UNSUPPORTED).

• JavaScript dialogs can block the originating browser command; handle them from an independent MCP request.

• Closed shadow roots and complex OOPIFs still require dedicated validation.

• Deep traversal is more expensive than page_get_tree and should be used explicitly.

• Downloads depend on Pydoll's expect_download flow and must remain in the controlled runtime dir.

• Uploads use the local source policy by default. Set PYDOLL_MCP_UPLOAD_POLICY=restricted when every source must be inside the runtime directories or PYDOLL_MCP_UPLOAD_ALLOWLIST.

• operation_cancel applies to waits and direct HTTP operations that receive an explicit caller-provided operation_id.

• Direct HTTP supports HTTP and HTTPS proxies. SOCKS proxy sessions return UNSUPPORTED rather than bypassing the configured browser proxy.

• Direct HTTP shares cookies, user agent, and supported proxy settings, but not Chromium's TLS fingerprint, HTTP cache, service workers, CORS behavior, or client certificates.

License

MIT