upwork-mcp

Un servidor del Protocolo de Contexto de Modelos (MCP) que conecta a Claude con Upwork, permitiendo a los agentes de IA buscar trabajos, analizar oportunidades, enviar propuestas y gestionar las comunicaciones con los clientes de forma autónoma.

Funciona para cualquier nicho de trabajo independiente: desarrollo, diseño, redacción, marketing, automatización y más.

Características

Herramienta	Descripción
`search_jobs`	Busca trabajos en Upwork por palabra clave, tipo, presupuesto y nivel de experiencia
`get_job_details`	Obtiene la descripción completa del trabajo, preguntas de selección y el historial del cliente
`analyze_job`	Puntúa un trabajo de 0 a 100 según el ajuste al nicho, calidad del cliente, presupuesto, competencia y claridad
`submit_proposal`	Escribe y envía automáticamente una propuesta con carta de presentación y oferta personalizadas
`get_proposals`	Lista las propuestas enviadas y su estado actual
`get_messages`	Lee conversaciones y comprueba si hay mensajes sin leer
`send_message`	Responde a los clientes en conversaciones en curso
`get_profile`	Visualiza tu perfil de freelancer, puntuación JSS y saldo de connects
`update_profile`	Actualiza el título, resumen y habilidades de tu perfil de freelancer
`manual_login`	Captura cookies de sesión desde una pestaña de Chrome ya iniciada

Arquitectura

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

La división entre gateway y worker significa que puedes actualizar la lógica de las herramientas sin reiniciar Claude o tu cliente MCP.

Requisitos previos

Node.js 20+
Docker + Docker Compose
Google Chrome instalado
Una cuenta de freelancer en Upwork

Inicio rápido (Docker)

1. Clonar y configurar

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

Edita .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. Iniciar Chrome con CDP

connect-chrome-docker.bat

Esto inicia Chrome con depuración remota + un proxy CDP que permite la conexión de Docker.

3. Iniciar el worker

docker compose up -d

4. Capturar tu sesión

En Claude, llama a manual_login: extrae las cookies de tu pestaña de Chrome iniciada y guarda la sesión. Solo necesitas hacer esto una vez (o después de que tu sesión expire).

Conectar a Claude Code

Añádelo a tu configuración de MCP (~/.claude/claude_desktop_config.json):

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

O mediante la CLI:

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

Desarrollo local (Recarga en caliente)

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

El gateway (dist/gateway.js) se ejecuta por separado y actúa como proxy hacia el worker local; los cambios en cualquier archivo de herramienta recargan el worker al instante sin reiniciar Claude.

Flujo de trabajo recomendado para el agente

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

Ejemplo de prompt para el agente

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

Puntuación de análisis de trabajo

La herramienta analyze_job puntúa cada trabajo en 5 dimensiones:

Dimensión	Puntos máx.	Qué mide
Ajuste al nicho	30	Coincidencia de palabras clave entre el trabajo y tu `FREELANCER_NICHE`
Calidad del cliente	25	Valoración, gasto total, tasa de contratación, pago verificado
Ajuste presupuestario	20	Presupuesto vs tu tarifa objetivo, valor estimado del proyecto
Competencia	10	Número de propuestas existentes (menos es mejor)
Claridad del proyecto	10	Detalle de la descripción, habilidades listadas, presupuesto especificado
Banderas rojas	-5 cada una	Alcance vago, señales de bajo presupuesto, sin historial del cliente

Calificaciones:

Calificación	Puntuación	Acción
A+	90–100	POSTULARSE AHORA — alta prioridad
A	75–89	POSTULARSE — gran oportunidad
B	60–74	POSTULARSE — vale la pena intentarlo
C	45–59	CONSIDERAR — ajuste marginal
D	30–44	OMITIR
F	<30	EVITAR

Estructura del proyecto

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

Notas

Gestión de sesiones

El inicio de sesión se gestiona manualmente mediante manual_login. Abre Chrome, inicia sesión en Upwork normalmente (incluyendo cualquier 2FA), luego llama a manual_login: captura todas las cookies y las guarda para que Playwright las reutilice.

Detección de bots

Upwork puede detectar actividad inusual. Utiliza intervalos de solicitud razonables y no ejecutes el agente de forma continua. El servidor se conecta a tu perfil real de Chrome mediante CDP, que se comporta más como un navegador real que como una automatización sin interfaz gráfica.

Estabilidad de selectores

La interfaz de usuario de Upwork cambia periódicamente. Es posible que los selectores basados en navegador en src/tools/ necesiten actualizarse si la interfaz se rediseña.

Uso ético

Automatiza solo tu propia cuenta
Cumple con los Términos de servicio de Upwork
Revisa las propuestas antes de enviarlas en entornos de producción

Licencia

MIT

upwork-mcp

upwork-mcp

Características

Arquitectura

Requisitos previos

Inicio rápido (Docker)

1. Clonar y configurar

2. Iniciar Chrome con CDP

3. Iniciar el worker

4. Capturar tu sesión

Conectar a Claude Code

Desarrollo local (Recarga en caliente)

Flujo de trabajo recomendado para el agente

Ejemplo de prompt para el agente

Puntuación de análisis de trabajo

Estructura del proyecto

Notas

Gestión de sesiones

Detección de bots

Estabilidad de selectores

Uso ético

Licencia

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API