# 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

## Installation

```bash
# 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](https://www.upwork.com/developer/keys)
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

```bash
# 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):

```json
{
  "mcpServers": {
    "upwork": {
      "command": "node",
      "args": ["/path/to/upwork-mcp-server/dist/index.js"],
      "env": {
        "UPWORK_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}
```

### Command Line

```bash
# 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
| Tool | Description |
|------|-------------|
| `upwork_search_jobs` | Search jobs with filters |
| `upwork_get_job` | Get detailed job information |
| `upwork_list_saved_jobs` | List your saved jobs |
| `upwork_save_job` | Save/unsave a job |
| `upwork_get_job_recommendations` | Get personalized recommendations |

### Proposals
| Tool | Description |
|------|-------------|
| `upwork_list_proposals` | List your proposals |
| `upwork_get_proposal` | Get proposal details |
| `upwork_submit_proposal` | Submit a new proposal |
| `upwork_update_proposal` | Update an existing proposal |
| `upwork_withdraw_proposal` | Withdraw a proposal |
| `upwork_get_proposal_stats` | Get proposal statistics |

### Contracts
| Tool | Description |
|------|-------------|
| `upwork_list_contracts` | List your contracts |
| `upwork_get_contract` | Get contract details |
| `upwork_get_work_diary` | Get work diary entries |
| `upwork_list_milestones` | List contract milestones |
| `upwork_submit_milestone` | Submit milestone work |
| `upwork_request_payment` | Request payment |
| `upwork_end_contract` | End a contract |

### Profile & Earnings
| Tool | Description |
|------|-------------|
| `upwork_get_profile` | Get freelancer profile |
| `upwork_update_profile` | Update your profile |
| `upwork_get_earnings` | Get earnings report |
| `upwork_get_transactions` | Get transaction history |
| `upwork_get_connects` | Get Connects balance |
| `upwork_get_job_success_score` | Get your JSS |

### Messages
| Tool | Description |
|------|-------------|
| `upwork_list_messages` | List message rooms/conversations |
| `upwork_send_message` | Send a message |

## 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

```bash
# 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](https://developers.upwork.com/)
- [Upwork GraphQL API](https://www.upwork.com/developer/documentation/graphql)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)