2eb9248aef
Multi-platform freelance automation MCP server. Phase 1 — Upwork adapter (11 tools): - Search/filter jobs (14 params, server + post filters) - Get job details with client intelligence - Submit proposals with cover letters - List/status proposals - List contracts by status/type - Get contract details with milestones - List message rooms with unread counts - Send messages - Get freelancer profile - Check connects balance - Auth status check Architecture: Platform adapter pattern with abstract base class. Auth: OAuth 2.0 with automatic token refresh. Tools registered at startup via MCP SDK protocol.
82 lines
2.2 KiB
Markdown
82 lines
2.2 KiB
Markdown
# 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
|