upwork-mcp

Claude를 Upwork에 연결하여 AI 에이전트가 작업을 검색하고, 기회를 분석하며, 제안서를 제출하고, 클라이언트와의 커뮤니케이션을 자율적으로 관리할 수 있게 해주는 Model Context Protocol (MCP) 서버입니다.

개발, 디자인, 글쓰기, 마케팅, 자동화 등 모든 프리랜서 분야에서 사용할 수 있습니다.

기능

도구	설명
`search_jobs`	키워드, 유형, 예산, 숙련도별로 Upwork 작업 검색
`get_job_details`	전체 작업 설명, 심사 질문 및 클라이언트 이력 가져오기
`analyze_job`	분야 적합성, 클라이언트 품질, 예산, 경쟁률, 명확성을 기준으로 작업 점수(0–100) 산정
`submit_proposal`	맞춤형 커버 레터와 입찰가를 포함하여 제안서를 자동으로 작성 및 제출
`get_proposals`	제출된 제안서 목록 및 현재 상태 확인
`get_messages`	대화 내용 읽기 및 읽지 않은 메시지 확인
`send_message`	진행 중인 대화에서 클라이언트에게 답장
`get_profile`	프리랜서 프로필, JSS 점수 및 Connects 잔액 확인
`update_profile`	프리랜서 프로필 제목, 개요 및 기술 업데이트
`manual_login`	이미 로그인된 Chrome 탭에서 세션 쿠키 캡처

아키텍처

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

게이트웨이/워커 분리 구조를 통해 Claude나 MCP 클라이언트를 재시작하지 않고도 도구 로직을 업데이트할 수 있습니다.

사전 요구 사항

Node.js 20+ 버전
Docker + Docker Compose
Google Chrome 설치
Upwork 프리랜서 계정

빠른 시작 (Docker)

1. 복제 및 구성

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

.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. CDP로 Chrome 시작

connect-chrome-docker.bat

이 명령은 원격 디버깅과 Docker가 연결할 수 있는 CDP 프록시를 사용하여 Chrome을 실행합니다.

3. 워커 시작

docker compose up -d

4. 세션 캡처

Claude에서 manual_login을 호출하면 로그인된 Chrome 탭에서 쿠키를 추출하여 세션을 저장합니다. 이 작업은 한 번만 수행하면 됩니다(세션 만료 시 다시 수행).

Claude Code에 연결

MCP 구성(~/.claude/claude_desktop_config.json)에 추가:

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

또는 CLI를 통해:

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

로컬 개발 (핫 리로드)

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

게이트웨이(dist/gateway.js)가 별도로 실행되며 로컬 워커로 프록시를 전달합니다. 도구 파일이 변경되면 Claude를 재시작할 필요 없이 워커가 즉시 다시 로드됩니다.

권장 에이전트 워크플로우

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

에이전트 프롬프트 예시

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

작업 분석 점수 산정

analyze_job 도구는 각 작업을 5가지 차원에서 점수를 매깁니다:

차원	최대 점수	측정 항목
분야 적합성	30	작업과 `FREELANCER_NICHE` 간의 키워드 일치도
클라이언트 품질	25	평점, 총 지출액, 채용률, 결제 인증 여부
예산 적합성	20	예산 대비 목표 단가, 예상 프로젝트 가치
경쟁률	10	기존 제안서 수 (적을수록 좋음)
프로젝트 명확성	10	설명의 상세함, 나열된 기술, 명시된 예산
주의 사항	-5 (각)	모호한 범위, 저예산 신호, 클라이언트 이력 없음

등급:

등급	점수	조치
A+	90–100	지금 지원 — 우선순위 높음
A	75–89	지원 — 좋은 기회
B	60–74	지원 — 추진할 가치 있음
C	45–59	고려 — 적합성 낮음
D	30–44	건너뛰기
F	<30	피하기

프로젝트 구조

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

참고 사항

세션 관리

로그인은 manual_login을 통해 수동으로 처리됩니다. Chrome을 열고 Upwork에 정상적으로 로그인(2FA 포함)한 다음 manual_login을 호출하면 모든 쿠키가 캡처되어 Playwright가 재사용할 수 있도록 저장됩니다.

봇 탐지

Upwork는 비정상적인 활동을 탐지할 수 있습니다. 합리적인 요청 간격을 사용하고 에이전트를 지속적으로 실행하지 마십시오. 이 서버는 CDP를 통해 실제 Chrome 프로필에 연결되므로 헤드리스 자동화보다 실제 브라우저처럼 동작합니다.

선택자 안정성

Upwork의 UI는 주기적으로 변경됩니다. UI가 재설계될 경우 src/tools/의 브라우저 기반 선택자를 업데이트해야 할 수 있습니다.

윤리적 사용

본인의 계정만 자동화하십시오.
Upwork 이용 약관을 준수하십시오.
프로덕션 환경에서 사용 시 제출 전 제안서를 검토하십시오.

라이선스

MIT

upwork-mcp

upwork-mcp

기능

아키텍처

사전 요구 사항

빠른 시작 (Docker)

1. 복제 및 구성

2. CDP로 Chrome 시작

3. 워커 시작

4. 세션 캡처

Claude Code에 연결

로컬 개발 (핫 리로드)

권장 에이전트 워크플로우

에이전트 프롬프트 예시

작업 분석 점수 산정

프로젝트 구조

참고 사항

세션 관리

봇 탐지

선택자 안정성

윤리적 사용

라이선스

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API