Upwork MCP Server
MCP (Model Context Protocol) server for Upwork via browser automation. Enables Claude Code to search jobs, manage proposals, messages, and contracts on Upwork.
Features
- Job Search: Search and filter Upwork jobs by keywords, budget, experience level, etc.
- Job Details: Get comprehensive information about specific job postings
- Profile: View your freelancer profile, connects balance, and stats
- Proposals: View, submit, and withdraw proposals
- Messages: Read and send messages in Upwork inbox
- Contracts: View active and past contracts, work diary entries
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 sync
Authentication
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 --login
This will:
- Start Chrome with
--remote-debugging-port=9222 - Navigate 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 --check
Clear session
uv run upwork-mcp --logout
Usage
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
Examples
Search for Python developer jobs
Search for Python developer jobs on Upwork with budget over $1000
Get job details
Get details for this Upwork job: https://www.upwork.com/jobs/~01234567890
Check proposals
Show my active proposals on Upwork
Read messages
Check my Upwork messages
CLI 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.py
Running tests
uv run python scripts/test_all.py
Session 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 --login
CAPTCHA or Cloudflare challenge
Run with visible browser to solve manually:
uvx upwork-mcp --no-headless
Browser not found
# Install Chromium for Patchright
uvx patchright install chromium
License
Apache 2.0
