Skillget

upwork-mcp-server

mcp
Security Audit
Warn
Health Warn
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 5 GitHub stars
Code Warn
  • network request — Outbound network request in src/auth/oauth.ts
  • network request — Outbound network request in src/common/api-client.ts
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

Open-source MCP server for Upwork's GraphQL API — search jobs, manage contracts, send messages, and more through AI agents like Claude

README.md

Upwork MCP Server

⚠️ Archived / no longer maintained. Upwork has released its own official MCP server. Please use that instead of this project. This repository is kept read-only for reference only.

An open-source Model Context Protocol server that connects AI agents to the Upwork API — enabling agentic job discovery, client intelligence, and freelancer workflow automation.

Why This Exists

Freelancers spend hours browsing job boards, evaluating fit, and writing proposals. AI agents are great at this kind of work — filtering, summarizing, drafting — but they need a standardized way to access the data.

This MCP server gives any MCP-compatible AI client (Claude Desktop, custom agents, etc.) direct access to Upwork's API through a clean, tool-based interface.

Features

  • 15 agentic tools covering the full freelancer workflow: discover → score → propose → manage → communicate
  • OAuth 2.0 authentication — Secure localhost callback flow with automatic token refresh
  • Composite scoring — score_opportunity rates jobs 0-100 across client quality, budget fit, competition, and skill match
  • GraphQL + REST — Uses Upwork's GraphQL API with REST fallbacks where needed
  • Rate limiting — Token bucket (10/sec, 300/min, 40K/day) with exponential backoff
  • Structured errors — Typed error categories with retryability flags and actionable messages
  • Poll notifications — Stateful diffing for new messages, proposal updates, and job matches

Quick Start

Prerequisites

Setup

# Clone and install
git clone https://github.com/AbbottDevelopments/upwork-mcp-server.git
cd upwork-mcp-server
npm install

# Configure credentials
cp .env.example .env
# Edit .env with your UPWORK_CLIENT_ID and UPWORK_CLIENT_SECRET

# Build
npm run build

# Authenticate (one-time OAuth flow)
npm run auth

# Run the server
npm start

Connect to Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "upwork": {
      "command": "node",
      "args": ["/path/to/upwork-mcp-server/dist/index.js"],
      "env": {
        "UPWORK_CLIENT_ID": "your-client-id",
        "UPWORK_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Connect to Claude Code

claude mcp add upwork -- node /path/to/upwork-mcp-server/dist/index.js

Tools

Tool Description
search_jobs Search Upwork jobs with 15+ server-side filters
get_job_details Full job posting with embedded client intelligence
score_opportunity Composite 0-100 quality scoring with red/yellow/green flags
analyze_client Deep client risk assessment from a job posting
get_my_profile Your freelancer profile, skills, rate, and JSS
get_connects_balance Available connects before applying
search_freelancers Competitor research by skills, rate, JSS, country
track_proposals List proposals with status and outcomes
list_contracts Active/ended contracts with filtering
get_contract_details Full contract with milestones and earnings
manage_milestones Create, edit, or request approval on milestones
get_earnings_report Earnings and time reports by period or custom range
list_messages Message rooms with unread counts and previews
send_message Send a message in an existing room
poll_notifications Check for new messages, proposal updates, and job matches

Architecture

See docs/architecture.md for diagrams showing how the system connects — also available as an Excalidraw file for interactive editing.

For implementation details, see the technical specification.

Project Structure

src/
  index.ts              # MCP server entry point
  auth/
    oauth.ts            # OAuth 2.0 authorization flow
    token-store.ts      # Persistent token storage (~/.upwork-mcp/)
  common/
    api-client.ts       # Upwork API client with auth + rate limiting
    errors.ts           # Structured error types
    rate-limiter.ts     # Request throttling
    poll-store.ts       # Polling state management
    types.ts            # TypeScript type definitions
  graphql/
    queries.ts          # Read operations (jobs, profiles, contracts)
    mutations.ts        # Write operations (proposals, messages)
  operations/           # High-level MCP tool implementations

Development

# Watch mode (rebuilds on change)
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

Status

All 15 tools implemented — OAuth flow, API client, rate limiting, and all four phases (scaffold, core tools, work management, communication) are built and reviewed. Ready for live API testing with Upwork credentials.

Contributing

Issues and PRs welcome. If you're a freelancer who wants specific Upwork workflows exposed as MCP tools, open an issue describing your use case.

License

MIT — see LICENSE for details.

Author

Built by Abbott Developments — AI automation and process consulting for operations-heavy businesses.

Reviews (0)

No results found