@chinchillaenterprises/mcp-upwork/README.md

Modular Upwork MCP server for job search and proposal management via Upwork API

# MCP Upwork Server

[![NPM Version](https://img.shields.io/npm/v/@chinchillaenterprises/mcp-upwork)](https://www.npmjs.com/package/@chinchillaenterprises/mcp-upwork)

A comprehensive Model Context Protocol (MCP) server for Upwork API integration, providing 20+ powerful tools for managing freelancer and client workflows through natural language interactions with Claude.

## 🚀 Quick Start

```bash
# Install the server
claude mcp add upwork -s user \
  -e UPWORK_API_KEY=your_api_key \
  -e UPWORK_API_SECRET=your_api_secret \
  -e UPWORK_ACCESS_TOKEN=your_access_token \
  -- npx @chinchillaenterprises/mcp-upwork

# Start Claude and try it out
claude
# Try: "Search for JavaScript jobs on Upwork" or "Show me my active contracts"
```

## 📋 Available Tools

### 🔍 Job Search & Discovery
- **`upwork_search_jobs`** - Search for jobs with advanced filters (skills, budget, duration, etc.)
- **`upwork_get_job_details`** - Get detailed information about a specific job

### 📝 Proposals Management
- **`upwork_submit_proposal`** - Submit proposals with cover letters and pricing
- **`upwork_list_proposals`** - List your submitted proposals with status filters

### 📄 Contracts Management
- **`upwork_list_contracts`** - View your active and completed contracts
- **`upwork_get_contract_details`** - Get detailed contract information

### ⏰ Work Diary & Time Tracking
- **`upwork_get_work_diary`** - View work diary entries for specific dates
- **`upwork_log_time`** - Log time for hourly contracts

### 💬 Messages & Communication
- **`upwork_list_messages`** - List conversations and messages
- **`upwork_send_message`** - Send messages to clients or freelancers

### 💰 Earnings & Reports
- **`upwork_get_earnings`** - Get earnings reports for different periods

### 👤 Profile Management
- **`upwork_get_profile`** - View your Upwork profile
- **`upwork_update_profile`** - Update profile information (title, skills, rates)

### 🎯 Milestones (Fixed-Price Projects)
- **`upwork_create_milestone`** - Create milestones for fixed-price contracts
- **`upwork_release_milestone`** - Release milestone payments (clients)

### 🔗 Connects Management
- **`upwork_get_connects_balance`** - Check your current connects balance
- **`upwork_purchase_connects`** - Purchase additional connects

### 👥 Client Tools
- **`upwork_search_freelancers`** - Search for freelancers (client feature)
- **`upwork_post_job`** - Post new jobs (client feature)

## 🔧 Installation

### Prerequisites
- An Upwork account with API access
- Claude Code installed
- Your Upwork API credentials (Key, Secret, Access Token)

### Getting API Credentials

1. **Create an Upwork App**:
   - Go to [Upwork Developers](https://developers.upwork.com/)
   - Create a new app to get your API Key and Secret
   - Request API access if you haven't already

2. **OAuth 2.0 Flow**:
   - Use the API Key and Secret to initiate OAuth 2.0 flow
   - Get the Access Token after user authorization
   - Store the Access Token securely

### Environment Variables

```bash
UPWORK_API_KEY=your_api_key_here
UPWORK_API_SECRET=your_api_secret_here
UPWORK_ACCESS_TOKEN=your_access_token_here
```

## 🎯 Use Cases

### For Freelancers
- **Job Discovery**: "Find React development jobs under $50/hour"
- **Proposal Management**: "Submit a proposal for job ID 12345 with my standard cover letter"
- **Time Tracking**: "Log 4 hours of work for today on contract ABC123"
- **Earnings Analysis**: "Show me my earnings for this month"
- **Profile Optimization**: "Update my hourly rate to $75"

### For Clients
- **Talent Search**: "Find Node.js experts with 90%+ job success score"
- **Job Posting**: "Post a new WordPress development job"
- **Project Management**: "Show me the work diary for my developer"
- **Milestone Management**: "Release the milestone payment for project XYZ"

## 🔒 Security Features

- Environment variable-based credential management
- OAuth 2.0 token authentication
- Rate limiting compliance
- Error handling for API failures
- Input validation with Zod schemas

## 📚 API Coverage

This MCP server implements tools for all major Upwork API endpoints:

### Core Areas Covered
- **Jobs API**: Search, details, posting
- **Contracts API**: Listing, details, management
- **Proposals API**: Submission, tracking
- **Time Reports API**: Work diary, time logging
- **Messages API**: Communication management
- **Financial Reports API**: Earnings, payments
- **Profiles API**: User information, updates
- **HR API**: Milestones, releases

### Authentication
- OAuth 2.0 flow support
- Token refresh handling
- Secure credential storage

## 🚦 Rate Limits

The server respects Upwork's API rate limits:
- Standard rate limits apply per endpoint
- Automatic error handling for 429 responses
- Graceful degradation on rate limit exceeded

## 🔍 Example Queries

```bash
# Search for specific jobs
"Find Python jobs with budgets over $1000"

# Manage proposals
"List my active proposals and their status"

# Track earnings
"Show me my earnings breakdown for last month"

# Time management
"Log 3 hours of frontend development work for today"

# Profile updates
"Update my profile to include React and TypeScript skills"

# Client management
"Find freelancers with 5-star ratings in graphic design"
```

## 🛠️ Development

```bash
# Clone and install
git clone <repository>
cd mcp-upwork
npm install

# Build
npm run build

# Development mode
npm run dev
```

## 📄 API Documentation

For detailed API information, visit:
- [Upwork Developer Documentation](https://developers.upwork.com/)
- [OAuth 2.0 Setup Guide](https://developers.upwork.com/api/authentication)
- [API Rate Limits](https://developers.upwork.com/api/rate-limits)

## 🔧 Configuration

### Claude Desktop Config

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "mcp-upwork": {
      "command": "npx",
      "args": ["@chinchillaenterprises/mcp-upwork"],
      "env": {
        "UPWORK_API_KEY": "your_api_key",
        "UPWORK_API_SECRET": "your_api_secret", 
        "UPWORK_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}
```

### Claude Code Project Config

```bash
claude mcp add upwork -s project \
  -e UPWORK_API_KEY=your_api_key \
  -e UPWORK_API_SECRET=your_api_secret \
  -e UPWORK_ACCESS_TOKEN=your_access_token \
  -- npx @chinchillaenterprises/mcp-upwork
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## 📝 License

MIT License - see LICENSE file for details.

## 🆘 Support

- [Issue Tracker](https://github.com/ChinchillaEnterprises/ChillMCP/issues)
- [Upwork API Documentation](https://developers.upwork.com/)
- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)

## 🎉 What's Next?

This MCP server provides comprehensive Upwork integration. Future enhancements may include:
- Webhook support for real-time notifications
- Advanced analytics and reporting
- Automated proposal templates
- Integration with calendar apps for time tracking
- Team management features for agencies

Happy freelancing! 🚀