Upwork

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

• Node.js 18+
• Upwork API credentials (developer portal)

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

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.