Upwork MCP Server
Provides browser-automation tools for Upwork, enabling job searches with filters, reading job details, profile and connects balance, profile stats, proposals, messages, unread counts, and contracts, as well as submitting proposals, sending messages, and withdrawing proposals.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Upwork MCP Server find me recent low-competition jobs with verified payment over $50/hr"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Upwork MCP Server
MCP (Model Context Protocol) server for Upwork via browser automation — search jobs, read your profile / connects / proposals, and (unverified) manage proposals, messages, and contracts from an MCP client such as Claude Code.
Fork. Based on vanooo/upwork-mcp by Ivan Solskiy. This fork adds real Upwork search-filter passthrough (competition, verified-payment, budget/rate floors, sorting) and rewrites several read tools whose scrapers had drifted against Upwork's current markup (they were returning
{}or the wrong element). See Tool status for exactly what is verified vs. untested — nothing here is claimed to work that hasn't been run.
Job search filters
upwork_search_jobs passes through Upwork's real search-URL grammar (the previous version silently dropped budget/category and hardcoded the sort order):
Param | Effect |
| keywords (supports |
|
|
|
|
|
|
| fixed-price budget range (USD) |
| minimum hourly rate (USD/hr) |
| only clients with a verified payment method |
| only jobs with fewer than 10 proposals so far |
| only clients who have hired at least once |
| client location, e.g. |
| max results (1–50) |
Every result carries the proposal count (competition) when Upwork exposes it — the key signal for finding winnable jobs.
Related MCP server: Upwork MCP Server
Tool status
Honest state as of this fork (browser-scraping tools drift when Upwork changes its markup):
Verified working — read-only, tested live:
upwork_check_session,upwork_search_jobs,upwork_get_job_details,upwork_get_connects_balance,upwork_get_my_profile,upwork_get_profile_stats,upwork_get_proposals,upwork_get_messages,upwork_get_unread_count(the last two verified against an empty inbox — the correct URL is now/ab/messages/rooms; per-conversation row parsing hasn't yet been seen with a live conversation)Present but NOT tested — they take real, billable or outward actions, so exercise deliberately:
upwork_submit_proposal,upwork_send_message,upwork_withdraw_proposalURL corrected but content parsing not yet validated against a live conversation:
upwork_get_conversationNot yet verified against current Upwork markup (may need the same text-parsing fix):
upwork_get_proposal_details,upwork_get_contracts,upwork_get_contract_details,upwork_get_work_diary
How It Works
This MCP uses Chrome DevTools Protocol (CDP) to connect to your real Chrome browser. This approach:
Bypasses Cloudflare's "automated test software" detection
Uses your real browser profile with history and cookies
Requires Chrome to be running with debug port enabled
Installation
Prerequisites
Python 3.12+
uv package manager
Google Chrome browser
Install from source
cd upwork-mcp
uv syncAuthentication
The server connects to Chrome via CDP (Chrome DevTools Protocol).
First-time setup
# Start login flow - opens Chrome with debug port
uv run upwork-mcp --loginThis will:
Start Chrome with
--remote-debugging-port=9222Navigate to Upwork login page
Wait for you to complete login (click Cloudflare checkbox, enter credentials)
Save session to
~/.upwork-mcp/chrome-profile/
Check session status
uv run upwork-mcp --checkClear session
uv run upwork-mcp --logoutUsage
With Claude Code (local development)
Add to your MCP settings (~/.config/claude-code/settings.json or workspace settings):
{
"mcpServers": {
"upwork": {
"command": "uv",
"args": ["--directory", "/path/to/upwork-mcp", "run", "upwork-mcp"]
}
}
}Available Tools
Status legend: ✅ verified live · ✅* verified on an empty inbox (URL fixed; populated parsing unconfirmed) · ⚠️ present, untested (real action) · ❓ not verified against current markup.
Tool | Description | Status |
| Search for jobs (see filters above) | ✅ |
| Get detailed job information | ✅ |
| Get your freelancer profile | ✅ |
| Get connects balance + recent history | ✅ |
| Get earnings / work-history stats | ✅ |
| Get your submitted proposals | ✅ |
| Check if session is valid | ✅ |
| Get inbox conversations | ✅* |
| Get unread message count | ✅* |
| Submit a proposal to a job | ⚠️ |
| Send a message | ⚠️ |
| Withdraw a submitted proposal | ⚠️ |
| Get messages in a conversation | ❓ |
| Get details of a specific proposal | ❓ |
| Get your contracts | ❓ |
| Get contract details | ❓ |
| Get work diary entries | ❓ |
| Close browser and cleanup | ❓ |
Examples
Search for Python developer jobs
Search for Python developer jobs on Upwork with budget over $1000Get job details
Get details for this Upwork job: https://www.upwork.com/jobs/~01234567890Check proposals
Show my active proposals on UpworkRead messages
Check my Upwork messagesCLI Options
upwork-mcp [OPTIONS]
Options:
--login Open browser for manual login
--check Check if session is valid
--logout Clear saved session
--no-headless Show browser window (debugging)
--timeout MS Page timeout in milliseconds (default: 30000)
--transport MCP transport type (default: stdio)Development
Project Structure
upwork-mcp/
├── pyproject.toml
├── README.md
├── src/upwork_mcp/
│ ├── __init__.py
│ ├── server.py # MCP server entry point
│ ├── browser/
│ │ ├── client.py # Patchright browser wrapper
│ │ └── auth.py # Login flow
│ ├── tools/
│ │ ├── jobs.py # Job search and details
│ │ ├── profile.py # Profile and connects
│ │ ├── proposals.py # Proposal management
│ │ ├── messages.py # Messaging
│ │ └── contracts.py # Contract management
│ └── utils/
│ ├── config.py # Configuration
│ └── logging.py # Logging setup
├── tests/
└── scripts/
└── test_all.pyRunning tests
uv run python scripts/test_all.pySession Storage
Session data is stored in ~/.upwork-mcp/profile/. This includes browser cookies and local storage that persist your Upwork login.
Troubleshooting
Session expired
# Re-authenticate
uvx upwork-mcp --loginCAPTCHA or Cloudflare challenge
Run with visible browser to solve manually:
uvx upwork-mcp --no-headlessBrowser not found
# Install Chromium for Patchright
uvx patchright install chromiumLicense
Apache 2.0
Available Tools
18 toolsupwork_check_sessionA
Check if the current Upwork session is valid.
Returns session status and whether re-login is needed.
Inputs: no named parameters.
upwork_close_sessionA
Close browser session and cleanup resources.
Call this when you're done using Upwork tools to free up resources.
Inputs: no named parameters.
upwork_get_connects_balanceA
Get current Upwork Connects balance.
Returns the number of available connects.
Inputs: no named parameters.
upwork_get_contract_detailsA
Get detailed information about a specific contract.
Returns full contract details including milestones, hours logged, and feedback.
Inputs: contract_url (required).
upwork_get_contractsB
Get your Upwork contracts.
Returns a list of contracts with client name, job title, status, and earnings.
Inputs: limit, status. Returns: result
upwork_get_conversationB
Get all messages in a specific conversation.
Returns conversation details with full message history.
Inputs: room_id (required), limit.
upwork_get_job_detailsB
Get detailed information about a specific Upwork job posting.
Returns comprehensive job details including description, client history, skills required, and application requirements.
Inputs: job_url (required).
upwork_get_messagesA
Get messages from Upwork inbox.
Returns a list of conversations with last message, sender info, and unread status.
Inputs: limit, room_id, unread_only. Returns: result
upwork_get_my_profileA
Get your Upwork freelancer profile information.
Returns profile data including name, title, hourly rate, JSS score, availability status, and skill tags.
Inputs: no named parameters.
upwork_get_profile_statsB
Get profile statistics including earnings and work history.
Returns stats like total earnings, hours worked, jobs completed.
Inputs: no named parameters.
upwork_get_proposal_detailsA
Get detailed information about a specific proposal.
Returns details including cover letter, bid, and any messages.
Inputs: proposal_url (required).
upwork_get_proposalsA
Get your submitted proposals on Upwork.
Returns a list of proposals with job title, status, bid amount, and dates.
Inputs: limit, status. Returns: result
upwork_get_unread_countA
Get count of unread messages.
Returns total unread message count.
Inputs: no named parameters.
upwork_get_work_diaryA
Get work diary entries for a contract.
Returns work diary with daily hours and earnings.
Inputs: contract_url (required), week_offset.
upwork_search_jobsB
Search for jobs on Upwork matching the specified criteria.
Returns a list of job summaries with title, budget, client info, and URL. All filters map to real Upwork search URL params (nothing is silently dropped).
Inputs: query (required), sort, limit, job_type, +8 more. Returns: result
upwork_send_messageC
Send a message in an Upwork conversation.
Returns send status.
Inputs: message (required), room_id (required).
upwork_submit_proposalA
Submit a proposal to an Upwork job.
IMPORTANT: This is a sensitive action that will spend Connects. Make sure the cover letter and rate/bid are correct before submitting.
Returns submission status and connects used.
Inputs: job_url (required), cover_letter (required), bid, rate, +1 more.
upwork_withdraw_proposalB
Withdraw a submitted proposal.
Returns withdrawal status.
Inputs: proposal_url (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Most tools target distinct resources and actions, such as job search/details, proposal list/detail/submit/withdraw, and contract list/detail/work diary. Minor overlap exists between get_messages (which returns conversations), get_conversation (which returns messages within one conversation), and get_unread_count, but descriptions clarify the boundaries well enough.
All 18 tools use the same upwork_ prefix followed by a consistent snake_case verb_noun pattern (e.g., upwork_get_proposal_details, upwork_submit_proposal, upwork_close_session). No mixed conventions or cryptic abbreviations appear.
With 18 tools, the set is slightly above the ideal 3-15 range, but each tool covers a meaningful operation across jobs, proposals, messaging, contracts, profile, and session management. The count is reasonable for a multi-feature Upwork freelancer workflow, though a few tools could potentially be consolidated.
The server covers core freelancer workflows: job discovery, proposal submission and withdrawal, messaging, contract details, work diary, profile information, and session lifecycle. Minor gaps exist (e.g., updating profile details, marking messages as read, or managing proposal drafts), but agents can work around these for most tasks.
Maintenance
Related MCP Connectors
OpeningsFirst reads 100,000+ company career sites in the US and India twice a day. Search jobs by role, city, skills or company; see what's new for your alerts; open a job in full; manage alerts and saved jobs; get help preparing an application. Requires an OpeningsFirst Pro plan.
The official Upwork MCP server, letting AI agents connect to Upwork and act on your behalf.
Open jobs from any company's careers site by name or domain, plus a search across 2.5M+ roles
Remote job boards, LinkedIn jobs, company ATS pages and Upwork jobs as tools. Runs on Apify.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceConnects AI agents to Upwork's GraphQL API, enabling job discovery, proposal management, profile tracking, and analytics.10 npm2MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with the Upwork freelance marketplace, including job search, proposal management, contract tracking, and earnings monitoring.261MIT
- AlicenseAqualityDmaintenanceEnables Claude to search jobs, manage proposals, messages, and contracts on Upwork via browser automation.18Apache 2.0
- FlicenseNot gradedqualityCmaintenanceEnables searching and analyzing Uplers talent board opportunities with market insights, as well as tracking applications and shortlists locally; optionally with authenticated access, it can manage a user's Uplers account, profile, and job applications.-