Upwork MCP Server

A Model Context Protocol (MCP) server for interacting with the Upwork freelance marketplace. Search jobs, manage proposals, track contracts, and monitor earnings - all through AI assistants like Claude.

Features

Job Search & Discovery

• Search Jobs: Find freelance opportunities with filters for skills, budget, category, experience level, and more
• Get Job Details: View complete job information including client history and requirements
• Save Jobs: Bookmark jobs for later review
• Get Recommendations: Personalized job suggestions based on your profile

Proposal Management

• Submit Proposals: Apply to jobs with cover letters and custom bids
• Track Proposals: Monitor proposal status (pending, accepted, declined)
• Update Proposals: Modify bids and cover letters before client response
• Withdraw Proposals: Cancel applications when needed
• View Statistics: Analyze your proposal success rates

Contract Management

• List Contracts: View all your active, paused, and completed contracts
• Contract Details: See terms, milestones, and feedback
• Work Diary: Track time logged on hourly contracts
• Milestones: Manage fixed-price project milestones
• Request Payment: Submit work and request payment
• End Contracts: Close contracts with feedback

Profile & Earnings

• View Profile: See your complete freelancer profile
• Update Profile: Modify title, skills, rate, and availability
• Earnings Reports: Detailed income breakdown by period and contract
• Transaction History: View all financial transactions
• Connects Balance: Monitor your proposal credits
• Job Success Score: Track your JSS and factors

Messaging

• List Conversations: View all message rooms with clients
• Read Messages: Access full conversation history
• Send Messages: Communicate with clients

Installation

# Clone or download the server
cd upwork-mcp-server

# Install dependencies
npm install

# Build the server
npm run build

Configuration

Getting Your Access Token

1. Go to Upwork API Center
2. Create a new API application or select an existing one
3. Request OAuth 2.0 credentials
4. Generate an access token with appropriate scopes

Environment Variables

# Required
UPWORK_ACCESS_TOKEN=your_oauth2_access_token

# Optional (for HTTP mode)
PORT=3000
TRANSPORT=http  # or 'stdio' (default)

Usage

With Claude Desktop

Add to your Claude Desktop configuration (~/.config/claude/claude_desktop_config.json on macOS/Linux or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "upwork": {
      "command": "node",
      "args": ["/path/to/upwork-mcp-server/dist/index.js"],
      "env": {
        "UPWORK_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Command Line

# Run with stdio (default)
UPWORK_ACCESS_TOKEN=xxx npm start

# Run as HTTP server
UPWORK_ACCESS_TOKEN=xxx npm start -- --http

# Development mode with auto-reload
UPWORK_ACCESS_TOKEN=xxx npm run dev

HTTP API

When running in HTTP mode, the server exposes:

• POST /mcp - MCP protocol endpoint
• GET /health - Health check

Available Tools

Jobs

Tool	Description
upwork_search_jobs	Search jobs with filters
upwork_get_job	Get detailed job information
upwork_list_saved_jobs	List your saved jobs
upwork_save_job	Save/unsave a job
upwork_get_job_recommendations	Get personalized recommendations

Proposals

Tool	Description
upwork_list_proposals	List your proposals
upwork_get_proposal	Get proposal details
upwork_submit_proposal	Submit a new proposal
upwork_update_proposal	Update an existing proposal
upwork_withdraw_proposal	Withdraw a proposal
upwork_get_proposal_stats	Get proposal statistics

Contracts

Tool	Description
upwork_list_contracts	List your contracts
upwork_get_contract	Get contract details
upwork_get_work_diary	Get work diary entries
upwork_list_milestones	List contract milestones
upwork_submit_milestone	Submit milestone work
upwork_request_payment	Request payment
upwork_end_contract	End a contract

Profile & Earnings

Tool	Description
upwork_get_profile	Get freelancer profile
upwork_update_profile	Update your profile
upwork_get_earnings	Get earnings report
upwork_get_transactions	Get transaction history
upwork_get_connects	Get Connects balance
upwork_get_job_success_score	Get your JSS

Messages

Tool	Description
upwork_list_messages	List message rooms/conversations
upwork_send_message	Send a message

Examples

Search for React Jobs

Use upwork_search_jobs with:
- query: "react developer"
- skills: ["react", "javascript", "typescript"]
- job_type: "hourly"
- experience_level: "intermediate"

Submit a Proposal

Use upwork_submit_proposal with:
- job_id: "~01abc123..."
- cover_letter: "Your personalized cover letter..."
- bid_amount: 50
- bid_type: "hourly"

Check Earnings

Use upwork_get_earnings with:
- start_date: "2024-01-01"
- end_date: "2024-12-31"

API Scopes

The server requires these Upwork API scopes:

• job:read - Search and view jobs
• proposal:read, proposal:write - Manage proposals
• contract:read, contract:write - Manage contracts
• profile:read, profile:write - Access and update profile
• earning:read - View earnings
• message:read, message:write - Access messages

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Clean build artifacts
npm run clean

License

MIT

Resources

• Upwork API Documentation
• Upwork GraphQL API
• MCP Protocol Specification