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.
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
# 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:
mcp_servers:
freelance:
command: "freelance-mcp"
env:
UPWORK_CLIENT_ID: "${UPWORK_CLIENT_ID}"
UPWORK_CLIENT_SECRET: "${UPWORK_CLIENT_SECRET}"
License
MIT