upwork-mcp

Ein Model Context Protocol (MCP)-Server, der Claude mit Upwork verbindet – und es KI-Agenten ermöglicht, autonom nach Jobs zu suchen, Möglichkeiten zu analysieren, Vorschläge einzureichen und Kundenkommunikation zu verwalten.

Funktioniert für jede Freelance-Nische: Entwicklung, Design, Schreiben, Marketing, Automatisierung und mehr.

Funktionen

Tool	Beschreibung
`search_jobs`	Suche nach Upwork-Jobs nach Stichwort, Typ, Budget, Erfahrungsstufe
`get_job_details`	Abrufen der vollständigen Stellenbeschreibung, Screening-Fragen und Kundenhistorie
`analyze_job`	Bewertung eines Jobs von 0–100 hinsichtlich Nischenpassung, Kundenqualität, Budget, Wettbewerb und Klarheit
`submit_proposal`	Automatisches Schreiben und Einreichen eines Vorschlags mit individuellem Anschreiben und Gebot
`get_proposals`	Auflisten eingereichter Vorschläge und deren aktuellen Status
`get_messages`	Konversationen lesen und auf ungelesene Nachrichten prüfen
`send_message`	Antworten auf Kunden in laufenden Konversationen
`get_profile`	Anzeigen Ihres Freelancer-Profils, JSS-Scores und Connects-Guthabens
`update_profile`	Aktualisieren Ihres Freelancer-Profiltitels, der Übersicht und der Fähigkeiten
`manual_login`	Erfassen von Sitzungs-Cookies aus einem bereits angemeldeten Chrome-Tab

Architektur

Claude Agent
    │
    ▼
MCP Gateway (stdio, never restarts)
    │  HTTP POST /tool
    ▼
Worker Server (port 47821, hot-reloads on code changes)
    │
    ▼
CDP Proxy (port 9223, rewrites Host headers)
    │
    ▼
Chrome on host (port 9222, Playwright CDP connection)
    │
    ▼
Upwork Web UI

Die Gateway/Worker-Aufteilung bedeutet, dass Sie die Tool-Logik aktualisieren können, ohne Claude oder Ihren MCP-Client neu zu starten.

Voraussetzungen

Node.js 20+
Docker + Docker Compose
Google Chrome installiert
Ein Upwork-Freelancer-Konto

Schnellstart (Docker)

1. Klonen und konfigurieren

git clone https://github.com/zcrossoverz/upwork-mcp.git
cd upwork-mcp
cp .env.example .env

Bearbeiten Sie .env:

UPWORK_EMAIL=your@email.com
UPWORK_PASSWORD=yourpassword

FREELANCER_NAME=Your Name
FREELANCER_TITLE=Your Professional Title
FREELANCER_NICHE=your,skills,here

BID_RATE_DEFAULT=40
BID_RATE_MIN=25
BID_RATE_MAX=100

2. Chrome mit CDP starten

connect-chrome-docker.bat

Dies startet Chrome mit Remote-Debugging + einem CDP-Proxy, der es Docker ermöglicht, eine Verbindung herzustellen.

3. Den Worker starten

docker compose up -d

4. Ihre Sitzung erfassen

Rufen Sie in Claude manual_login auf – es extrahiert Cookies aus Ihrem angemeldeten Chrome-Tab und speichert die Sitzung. Sie müssen dies nur einmal tun (oder nachdem Ihre Sitzung abgelaufen ist).

Mit Claude Code verbinden

Fügen Sie dies zu Ihrer MCP-Konfiguration hinzu (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "upwork": {
      "command": "node",
      "args": ["/absolute/path/to/upwork-mcp/dist/gateway.js"],
      "env": {
        "WORKER_PORT": "47821"
      }
    }
  }
}

Oder über die CLI:

claude mcp add upwork node /absolute/path/to/upwork-mcp/dist/gateway.js

Lokale Entwicklung (Hot Reload)

npm install
npm run worker   # starts tsc --watch + nodemon on dist/worker.js

Das Gateway (dist/gateway.js) läuft separat und leitet Anfragen an den lokalen Worker weiter – Änderungen an einer Tool-Datei laden den Worker sofort neu, ohne Claude neu zu starten.

Empfohlener Agent-Workflow

1. manual_login      → Capture session (first time / session expired)
2. get_profile       → Check connects balance before bidding
3. search_jobs       → Find relevant jobs by keyword
4. get_job_details   → Get full description + screening questions
5. analyze_job       → Score the opportunity (skip grade D or F)
6. submit_proposal   → Auto-bid with personalized cover letter
7. get_messages      → Check for client responses
8. send_message      → Reply to clients
9. get_proposals     → Track active proposals

Beispiel-Agent-Prompt

Search for freelance jobs matching my skills posted in the last 3 days.
For each job with grade A or B:
1. Get full job details
2. Analyze the opportunity
3. Write a personalized proposal highlighting my relevant experience
4. Submit at the recommended bid rate

Job-Analyse-Scoring

Das Tool analyze_job bewertet jeden Job in 5 Dimensionen:

Dimension	Max. Punkte	Was es misst
Nischenpassung	30	Stichwortübereinstimmung zwischen Job und Ihrer `FREELANCER_NICHE`
Kundenqualität	25	Bewertung, Gesamtausgaben, Einstellungsrate, Zahlung verifiziert
Budgetpassung	20	Budget vs. Ihr Zielstundensatz, geschätzter Projektwert
Wettbewerb	10	Anzahl bestehender Vorschläge (weniger = besser)
Projektklarheit	10	Detailgrad der Beschreibung, aufgeführte Fähigkeiten, angegebenes Budget
Warnsignale	-5 je	Vager Umfang, Niedrigbudget-Signale, keine Kundenhistorie

Noten:

Note	Punktzahl	Aktion
A+	90–100	JETZT BEWERBEN — hohe Priorität
A	75–89	BEWERBEN — starke Gelegenheit
B	60–74	BEWERBEN — verfolgenswert
C	45–59	ÜBERLEGEN — grenzwertige Passung
D	30–44	ÜBERSPRINGEN
F	<30	VERMEIDEN

Projektstruktur

upwork-mcp/
├── src/
│   ├── gateway.ts                # MCP stdio gateway (thin proxy, never restarts)
│   ├── worker.ts                 # HTTP tool server (hot-reloads via nodemon)
│   ├── config.ts                 # Environment configuration
│   ├── browser/
│   │   ├── browser-manager.ts    # Playwright CDP connection manager
│   │   └── upwork-auth.ts        # Session management
│   └── tools/
│       ├── search-jobs.ts
│       ├── get-job-details.ts
│       ├── analyze-job.ts        # Scoring engine
│       ├── submit-proposal.ts
│       ├── get-proposals.ts
│       ├── get-messages.ts
│       ├── send-message.ts
│       ├── get-profile.ts
│       ├── update-profile.ts
│       └── manual-login.ts       # CDP cookie extractor
├── cdp-proxy.cjs                 # Host-side proxy: Docker → Chrome (fixes Host header)
├── connect-chrome-docker.bat     # Launch Chrome + CDP proxy (for Docker use)
├── connect-chrome.bat            # Launch Chrome only (for local use)
├── Dockerfile
├── docker-compose.yml
└── .env.example

Hinweise

Sitzungsverwaltung

Der Login erfolgt manuell über manual_login. Öffnen Sie Chrome, melden Sie sich normal bei Upwork an (einschließlich 2FA), und rufen Sie dann manual_login auf – es erfasst alle Cookies und speichert sie zur Wiederverwendung durch Playwright.

Bot-Erkennung

Upwork kann ungewöhnliche Aktivitäten erkennen. Verwenden Sie angemessene Anfrageintervalle und lassen Sie den Agenten nicht kontinuierlich laufen. Der Server verbindet sich über CDP mit Ihrem echten Chrome-Profil, was sich eher wie ein echter Browser verhält als eine Headless-Automatisierung.

Selektor-Stabilität

Die Benutzeroberfläche von Upwork ändert sich regelmäßig. Browser-basierte Selektoren in src/tools/ müssen möglicherweise aktualisiert werden, wenn das UI neu gestaltet wird.

Ethische Nutzung

Automatisieren Sie nur Ihr eigenes Konto
Halten Sie sich an die Nutzungsbedingungen von Upwork
Überprüfen Sie Vorschläge vor dem Einreichen im produktiven Einsatz

Lizenz

MIT

upwork-mcp

upwork-mcp

Funktionen

Architektur

Voraussetzungen

Schnellstart (Docker)

1. Klonen und konfigurieren

2. Chrome mit CDP starten

3. Den Worker starten

4. Ihre Sitzung erfassen

Mit Claude Code verbinden

Lokale Entwicklung (Hot Reload)

Empfohlener Agent-Workflow

Beispiel-Agent-Prompt

Job-Analyse-Scoring

Projektstruktur

Hinweise

Sitzungsverwaltung

Bot-Erkennung

Selektor-Stabilität

Ethische Nutzung

Lizenz

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API