upwork-mcp-server

retailbox-automation/upwork-mcp-server

3.2

If you are the rightful owner of upwork-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Upwork MCP Server is a Model Context Protocol server designed for seamless integration with the Upwork API, enabling AI assistants to interact with Upwork for freelancers and agencies.

Tools
11
Resources
0
Prompts
0

Upwork MCP Server

Model Context Protocol (MCP) server for Upwork API integration. Enables AI assistants to interact with Upwork for freelancers and agencies.

Status: ✅ Production Ready | Total Tools: 19 | Verified Working: 11 (58%)

Features

For Freelancers

  • 🔍 Search and browse jobs
  • 📝 Submit and manage proposals
  • 💼 Track contracts and milestones
  • 💰 View earnings and financial reports
  • ⏰ Access work diary and timesheets
  • 💬 Send and receive messages
  • ⭐ View feedback and ratings

For Agencies

  • 👥 Manage team members and permissions
  • 📊 View team contracts and earnings
  • 💵 Control contractor rates
  • 📈 Access agency-wide reports

Installation

npm install

Configuration

  1. Copy .env.example to .env:
cp .env.example .env

  1. Get your Upwork API credentials:

    • Go to https://www.upwork.com/developer
    • Sign in to your Upwork account
    • Navigate to API Center
    • Request new API key (OAuth 2.0)
    • Fill in the application details
    • Wait for approval (up to 2 weeks)

  2. Add your credentials to .env:

UPWORK_CLIENT_ID=your_client_id
UPWORK_CLIENT_SECRET=your_client_secret
UPWORK_REDIRECT_URI=http://localhost:3000/callback

Usage

Development

npm run dev

Build

npm run build

Production

npm start

MCP Tools Available

✅ Verified Working Tools (11/19)

These tools are confirmed to work for all freelancers:

Jobs & Proposals
  • ✅ search_jobs - Search for jobs with filters
  • ✅ get_job_details - Get detailed job information
  • ✅ list_my_proposals - List your proposals
Contracts
  • ✅ list_contracts - List your contracts (active/completed)
  • ✅ get_contract_details - Get contract details
  • ✅ get_team_contracts - Get team contracts
Messages
  • ✅ list_rooms - List message rooms/chats
  • ✅ get_room_messages - Get messages from a room
  • ✅ send_message - Send a message
Profile & Reference
  • ✅ get_my_profile - Get your profile information
  • ✅ get_timezones - Get available timezones

🔧 Needs Verification (4/19)

These tools are implemented but need testing:

  • 🔧 get_proposal_details - Get detailed proposal information
  • 🔧 get_proposal_metadata - Get proposal metadata (engagement durations, etc.)
  • 🔧 get_contract_room - Get message room for a contract
  • 🔧 get_proposal_room - Get message room for a proposal

🔒 Agency/Team Required (3/19)

These tools require agency or team account permissions:

  • 🔒 get_earnings_report - Get earnings report (requires view_gds_hourly_data_from_client permission)
  • 🔒 get_billing_report - Get billing information (requires view_gds_charges_data_from_client permission)
  • 🔒 list_agency_members - List agency team members (requires agency account)

Note: These limitations are due to Upwork's account permission model, not API key permissions.

⚠️ Requires Specific Data (1/19)

  • ⚠️ get_work_diary - Get work diary for a contract (requires contract with time tracking enabled)

Documentation

Getting Started

  • - Complete installation and configuration guide
  • - Detailed documentation for all available tools
  • - Practical examples and workflows

Additional Resources

  • - More usage examples
  • - Token handling and refresh
  • - Notes for N8N users
  • - Architecture and organization
  • - Future development plans

Architecture

upwork-mcp-server/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── cli-auth.ts           # OAuth authentication CLI
│   ├── types/                # TypeScript type definitions
│   ├── auth/                 # OAuth 2.0 authentication
│   ├── api/                  # Upwork GraphQL API client
│   └── tools/                # MCP tool implementations
├── docs/
│   ├── SETUP_GUIDE.md        # Installation guide
│   ├── TOOLS.md              # Tools reference
│   ├── USAGE_GUIDE.md        # Usage examples
│   ├── reports/              # Technical reports
│   └── archive/              # Archived documentation
├── tests/                    # Test scripts
├── dist/                     # Compiled output
├── package.json
├── tsconfig.json
└── README.md

API Documentation

Requirements

  • Node.js 18+
  • Upwork account (freelancer or agency)
  • Approved Upwork API key (OAuth 2.0)

Rate Limits

  • 40,000 requests per day per API key
  • Access token TTL: 24 hours
  • Refresh token TTL: 2 weeks (from last use)

Security Notes

  • Never commit .env file to version control
  • Keep your API credentials secure
  • Rotate credentials regularly
  • Use refresh tokens to maintain access

License

MIT

Support

For issues related to: