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

Related MCP server: upwork-mcp

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

Proposals

Contracts

Profile & Earnings

Messages

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