# freelance-mcp

A **Model Context Protocol** server that connects AI agents to freelance platforms via their official APIs.

## Platforms

| Platform | Status | Auth | Capabilities |
|---|---|---|---|
| **Upwork** | ✅ Live | OAuth 2.0 | Search jobs, submit proposals, messages, contracts, profile |
| **Freelancer.com** | 🔧 Coming | OAuth 2.0 | Search projects, bid, messages, contracts |
| **Fiverr** | ❌ No public API | — | Read-only scraping only |

## Quick Start

```bash
# Install
pip install -e .

# Set Upwork API credentials
export UPWORK_CLIENT_ID="your_client_id"
export UPWORK_CLIENT_SECRET="your_client_secret"

# Run OAuth flow (one-time)
freelance-mcp-auth auth upwork

# Start the MCP server
freelance-mcp
```

## Tools

All tools are prefixed with the platform name:

### Upwork (`upwork_*`)

| Tool | Description |
|---|---|
| `upwork_search_jobs` | Search jobs with 15+ filters |
| `upwork_get_job_details` | Full job posting with client intelligence |
| `upwork_get_profile` | Your freelancer profile |
| `upwork_get_connects` | Check connects balance |
| `upwork_submit_proposal` | Submit a proposal with cover letter |
| `upwork_list_proposals` | Track submitted proposals |
| `upwork_list_contracts` | View active/ended contracts |
| `upwork_get_contract_details` | Full contract with milestones |
| `upwork_list_messages` | Message rooms with unread counts |
| `upwork_send_message` | Send a message |
| `upwork_check_auth` | Check authentication status |

## Architecture

```
freelance-mcp/
├── src/freelance_mcp/
│   ├── server.py           # MCP entry point
│   ├── platforms/
│   │   ├── base.py         # Abstract adapter
│   │   └── upwork.py       # Upwork GraphQL + REST
│   ├── auth/
│   │   ├── cli.py          # Auth CLI (freelance-mcp-auth)
│   │   └── token_store.py  # OAuth token persistence
│   └── config/
│       └── loader.py       # Config from environment
```

## Hermes Integration

Add to your `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  freelance:
    command: "freelance-mcp"
    env:
      UPWORK_CLIENT_ID: "${UPWORK_CLIENT_ID}"
      UPWORK_CLIENT_SECRET: "${UPWORK_CLIENT_SECRET}"
```

## License

MIT