Upwork MCP Server

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