Upwork MCP Server

A Model Context Protocol server that connects AI agents to Upwork's GraphQL API — enabling job discovery, proposal management, profile tracking, and analytics.

Features

• Official API Integration: Uses Upwork's GraphQL API with OAuth 2.0 authentication
• Job Search: Search and filter job postings with advanced criteria
• Proposal Management: Submit, update, track, and withdraw proposals
• Saved Jobs: Bookmark jobs for later review and get personalized recommendations
• Profile Management: View your freelancer profile, skills, and completeness
• Contract Tracking: Monitor active contracts and earnings
• Time Reports: Query work history and time logs
• Rate Limiting: Built-in rate limiting to stay within API quotas
• Type-Safe: Written in TypeScript with full type definitions

Quick Start

Option 1: npm (Recommended)

# Install globally
npm install -g @furkankoykiran/upwork-mcp

# Or use with npx (no installation needed)
npx @furkankoykiran/upwork-mcp

Option 2: With Claude Code (One-Line Setup)

claude mcp add upwork -- npx -y @furkankoykiran/upwork-mcp

Then set your credentials:

export UPWORK_CLIENT_ID="your_client_id"
export UPWORK_CLIENT_SECRET="your_client_secret"

And authenticate:

npx @furkankoykiran/upwork-mcp auth

Option 3: From Source

git clone https://github.com/furkankoykiran/upwork-mcp.git
cd upwork-mcp
npm install
npm run build

Authentication

1. Get API Credentials

1. Go to Upwork Developer Portal
2. Create a new API application
3. Note your Client ID and Client Secret

2. Configure and Authenticate

# Set your credentials as environment variables
export UPWORK_CLIENT_ID="your_client_id"
export UPWORK_CLIENT_SECRET="your_client_secret"

# Run authentication
npx @furkankoykiran/upwork-mcp auth

This will:

1. Open your browser with the Upwork OAuth authorization page
2. Wait for you to log in and authorize the application
3. Save your access token locally

3. Verify Authentication

npx @furkankoykiran/upwork-mcp check

Configuration

The server requires the following environment variables:

| Variable | Description | Required | |----------|-------------|----------| | UPWORK_CLIENT_ID | Your Upwork OAuth Client ID | Yes | | UPWORK_CLIENT_SECRET | Your Upwork OAuth Client Secret | Yes | | UPWORK_API_URL | Upwork GraphQL API URL (default: https://api.upwork.com/graphql) | No |

With Claude Code

Add to your MCP configuration (~/.config/claude-code/settings.json):

{
  "mcpServers": {
    "upwork": {
      "command": "npx",
      "args": ["-y", "@furkankoykiran/upwork-mcp"],
      "env": {
        "UPWORK_CLIENT_ID": "your_client_id",
        "UPWORK_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Available Tools

Profile Tools (4 tools)

| Tool | Description | |------|-------------| | get_profile | Get your freelancer profile, skills, rate, and Job Success Score | | get_profile_completeness | Check profile completeness score and missing fields | | get_skills | List all skills on your profile | | get_connects_balance | Get your current connects balance |

Job Search Tools (2 tools)

| Tool | Description | |------|-------------| | search_jobs | Search job postings with filters (keyword, budget, category, etc.) | | get_job_details | Get full details of a specific job posting |

Proposal Tools (6 tools)

| Tool | Description | |------|-------------| | list_proposals | List your submitted proposals with status filter | | get_proposal | Get detailed proposal information including cover letter | | submit_proposal | Submit a new proposal (uses Connects) | | update_proposal | Update an existing proposal (pending only) | | withdraw_proposal | Withdraw a submitted proposal | | get_proposal_stats | Get proposal statistics and success rates |

Saved Jobs Tools (3 tools)

| Tool | Description | |------|-------------| | list_saved_jobs | List your saved/bookmarked jobs | | save_job | Save or unsave a job to bookmarks | | get_job_recommendations | Get personalized job recommendations |

Contract Tools (2 tools)

| Tool | Description | |------|-------------| | list_contracts | List your active and past contracts | | get_contract_details | Get detailed information about a specific contract |

Analytics Tools (1 tool)

| Tool | Description | |------|-------------| | get_time_report | Get time report for work history and hours logged |

Total: 18 tools

Example Usage

Search for Jobs

Search for Upwork jobs with keyword "TypeScript" and hourly rate between $50-$100

Submit a Proposal (with Dry Run)

Submit a proposal for job ~0123456789012345678 with cover letter "I am experienced..." bid amount $75 hourly, dry_run=true

List Proposals

List my pending Upwork proposals

Save a Job

Save job ~0123456789012345678

Get Job Recommendations

Get personalized job recommendations

Safety Features

Dry Run Mode

All mutation tools (submit_proposal, update_proposal, withdraw_proposal) support a dry_run parameter that previews the action without executing it:

{
  "job_id": "~0123456789012345678",
  "cover_letter": "Your cover letter here...",
  "bid_amount": 50,
  "bid_type": "hourly",
  "dry_run": true
}

Validation

• Cover letters must be 50-5000 characters
• Bid amounts must be greater than 0
• Proposal updates only work on pending proposals

Rate Limits

The server implements conservative rate limiting to avoid exceeding Upwork's API quotas:

• 10 requests per second
• 300 requests per minute
• 40,000 requests per day

Rate limits are automatically enforced with token bucket algorithm.

Troubleshooting

Authentication Issues

# Clear existing token
npx @furkankoykiran/upwork-mcp logout

# Re-authenticate
npx @furkankoykiran/upwork-mcp auth

Token Expired

The server automatically attempts to refresh tokens when they expire. If this fails:

npx @furkankoykiran/upwork-mcp auth

Rate Limit Errors

If you hit rate limits, the server will automatically retry with exponential backoff. For persistent issues, wait a few minutes before retrying.

Development

# Clone the repository
git clone https://github.com/furkankoykiran/upwork-mcp.git
cd upwork-mcp

# Install dependencies
npm install

# Watch mode (rebuilds on changes)
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

See CONTRIBUTING.md for detailed contribution guidelines.

Project Structure

upwork-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── auth/                 # OAuth 2.0 authentication
│   ├── client/               # Upwork API client with rate limiting
│   ├── queries/              # GraphQL queries and mutations
│   ├── tools/                # MCP tool implementations
│   └── types/                # TypeScript type definitions
├── .github/
│   ├── workflows/            # CI/CD workflows (CI, CodeQL, Release, Stale)
│   ├── pull_request_template/
│   ├── ISSUE_TEMPLATE/       # Issue templates (Bug, Feature, Question)
│   ├── CONTRIBUTING.md       # Contribution guidelines
│   ├── CODE_OF_CONDUCT.md    # Community guidelines
│   ├── SECURITY.md           # Security policy
│   └── SUPPORT.md            # Support guidelines
├── dist/                     # Compiled output (gitignored)
├── node_modules/             # Dependencies (gitignored)
├── eslint.config.js          # ESLint configuration
├── tsconfig.json             # TypeScript configuration
├── package.json              # Project metadata
├── CHANGELOG.md              # Version history
├── LICENSE                   # MIT License
└── README.md                 # This file

License

MIT © Furkan Köykıran - see LICENSE file for details.

Links

• npm Package
• Documentation
• Contributing
• Code of Conduct
• Security Policy
• Support
• Changelog

Acknowledgments

• fieldjoshua/upwork-mcp-server - Reference for GraphQL mutations
• Upwork Developer Portal
• Model Context Protocol