xingzi-mcp

Xingzi 대행 MCP 서버 — AI가 소재 배포, 결과물 검토, 결제를 대신 처리해 드립니다.

npm version

소재 대행이란?

「소재 대행」은 KOC (Key Opinion Consumer) 홍보 모델입니다:

광고주 (귀하): 홍보 니즈가 있으며, 소재(이미지/영상/문구)를 준비하고 성과에 따라 비용을 지불할 의사가 있는 분
KOC (인플루언서): 각 소셜 플랫폼에서 계정을 운영하며, 콘텐츠를 게시하고 보상을 받을 의사가 있는 분
Xingzi 대행 플랫폼: 양측을 연결하는 중간 플랫폼으로, 작업 게시, 수락, 결과물 제출, 결제 등의 기능을 제공

이 MCP는 「광고주」 역할을 수행합니다 — 작업 게시, 결과물 검토, KOC에게 결제하기.

워크플로우

┌─────────────────────────────────────────────────────────┐
│                    广告主（你 + AI）                       │
│                                                         │
│  ① publish_task ──→ 发布任务（素材+要求+单价+人数）        │
│                         │                                │
│                         ▼                                │
│              KOC 在素材广场看到并领取                       │
│                         │                                │
│                         ▼                                │
│              KOC 发布到社交媒体，提交回执                   │
│                         │                                │
│  ③ list_postbacks ──→ 查看回执                            │
│                         │                                │
│  ④ audit_postback ──→ 审核（通过/拒绝）                    │
│                         │                                │
│  ⑤ pay_reward ──────→ 生成支付链接                        │
│                         │                                │
│                         ▼                                │
│              在微信中打开链接完成付款 ✅                     │
└─────────────────────────────────────────────────────────┘

설치 및 설정

전제 조건

Node.js >= 18
MCP를 지원하는 AI 도구 (Claude Code / Cursor / Windsurf / Cline 등)
Xingzi Zhutui(星子助推) 플랫폼 계정 (가입: https://m.xingziwenhua.com )
Xingzi 멤버십(VIP): 소재 대행 작업을 게시하려면 멤버십 자격이 필요합니다 (아래 설명 참조)

왜 멤버십이 필요한가요? Xingzi Zhutui 플랫폼은 멤버십 회원만 소재 대행 작업을 게시할 수 있도록 제한하고 있습니다. 이는 다음 두 가지 이유 때문입니다:
신용 및 이행: 멤버십 시스템은 플랫폼이 신용 위험과 계약 불이행 위험을 관리하여 광고주가 제때 결제할 수 있도록 보장합니다.
멤버십 혜택: 소재 대행 서비스 자체가 플랫폼이 멤버십 회원에게 제공하는 전용 부가 서비스입니다.
아직 회원이 아니시라면, Xingzi Zhutui 앱/H5의 「멤버십 센터」에서 가입하실 수 있습니다.

Claude Code

~/.claude/settings.json 파일을 편집하세요:

{
  "mcpServers": {
    "xingzi": {
      "command": "npx",
      "args": ["-y", "xingzi-mcp"],
      "env": {
        "XINGZI_MOBILE": "你的手机号",
        "XINGZI_PASSWORD": "你的密码"
      }
    }
  }
}

Cursor

.cursor/mcp.json 파일을 편집하세요:

{
  "mcpServers": {
    "xingzi": {
      "command": "npx",
      "args": ["-y", "xingzi-mcp"],
      "env": {
        "XINGZI_MOBILE": "你的手机号",
        "XINGZI_PASSWORD": "你的密码"
      }
    }
  }
}

Windsurf / 기타

해당 도구의 MCP 설정 파일에 동일한 설정을 추가하면 됩니다.

환경 변수 미설정 (수동 로그인)

env 필드를 비워두어도 됩니다. 처음 사용할 때 AI에게 login 도구를 호출하도록 요청하세요:

"Xingzi 대행에 로그인해 줘. 휴대폰 번호는 138xxxx, 비밀번호는 xxxx야."

사용 가능한 도구

총 11개의 도구가 광고주의 전체 운영 프로세스를 지원합니다:

인증 및 안내

도구	설명
`login`	플랫폼 로그인 (환경 변수 설정 시 자동 로그인)
`guide`	사용 가이드 및 가격 참고 확인

작업 게시

도구	설명
`publish_task`	핵심: 대행 작업 게시 (소재+요구사항+단가+인원)
`list_my_tasks`	게시한 모든 작업 목록 확인
`get_task_detail`	특정 작업의 상세 정보 확인
`delete_task`	작업 삭제

결과물 검토

도구	설명
`list_postbacks`	KOC가 제출한 결과물(작품 링크/스크린샷) 확인
`audit_postback`	결과물 검토: 승인 또는 거절

결제

도구	설명
`list_unpaid_awards`	미결제 목록 확인
`pay_reward`	위챗 결제 링크 생성 (전체 선택/단일 선택/금액 수정 지원)

지갑

도구	설명
`get_wallet`	잔액 확인 (총 수익/출금 가능/출금 완료/동결)

사용 예시

대행 작업 게시하기

你：帮我发一个代发任务
    素材是这张图 https://example.com/ad.jpg
    要求发到小红书，配文提到"夏日好物推荐"
    单价10元，最多50人

AI：[调用 publish_task]
    ✅ 任务发布成功！50 个名额，10 元/条。
    KOC 可以在素材广场看到并领取。

결과물 검토 및 결제하기

你：看看任务 1615 的回执，合格的帮我通过

AI：[调用 list_postbacks] 共 3 条回执
    - 66°C 提交了抖音链接 ✓
    - 小明 提交了小红书截图 ✓  
    - 用户A 截图模糊看不清 ✗

    [调用 audit_postback x3] 通过 2 条，拒绝 1 条

你：帮我打款

AI：[调用 pay_reward]
    待打款 2 人，共 20 元
    请在微信中打开此链接付款：https://m.xingziwenhua.com/spages/material/batchpay?id=1615
    
    💡 支付页面可以修改金额（表现好的可以加钱），也可以写奖励说明。

지갑 확인하기

你：钱包余额多少？

AI：[调用 get_wallet]
    总收益：11,290.36 元
    可提现：11,256.46 元
    已提现：33.90 元
    冻结中：0.00 元

가격 참고

작업 유형	권장 단가	설명
단순 공유	5-8 위안	소재를 직접 공유하고 간단한 문구 작성
이미지/문구	8-15 위안	KOC가 직접 문구 작성 필요
짧은 영상	15-30 위안	KOC가 영상 촬영/편집 필요

건당 5위안 미만의 작업은 수락률이 매우 낮습니다. MCP가 이를 사전에 알려드립니다.

작업 요구사항 작성 가이드

작업 요구사항(task_requirement)은 수락률과 완성도에 결정적인 영향을 미칩니다.

좋은 작업 요구사항 예시

发布到小红书，图文形式。
配文需包含"XXX品牌夏日新品"关键词，200字以内。
发布后截图+笔记链接作为回执。

发布到抖音，直接使用我提供的视频素材。
视频标题和文案自由发挥，需要 @XXX品牌 官方账号。
发布后提交视频链接。

포함 권장 사항

게시할 플랫폼 (샤오홍슈 / 더우인 / 지후 / 웨이보 등)
형식 (이미지/문구 / 영상 / 게시글)
핵심 문구 포인트 (브랜드명, 키워드, 해시태그 등)
게시 시간 요구사항 (있는 경우)

피해야 할 사항

❌ 여러 플랫폼에 동시에 게시 요구 (작업을 나누는 것이 더 좋습니다)
❌ 팔로워 수 제한 (단가를 대폭 높이지 않는 한)
❌ 독창적인 긴 영상 요구 (복잡도가 높아 완성률이 낮음)
❌ 상단 고정/추천/인기 게시물 요구 (통제 불가능한 요소)
❌ 작업 설명이 너무 길고 복잡함 (KOC가 바로 이탈함)

기술 아키텍처

전체 설계

┌──────────────────┐     stdio      ┌───────────────────┐
│  AI 工具          │ ◄──────────► │  xingzi-mcp       │
│  (Claude/Cursor)  │   MCP协议     │  (Node.js Server) │
└──────────────────┘               └─────────┬─────────┘
                                             │ HTTPS
                                             ▼
                                   ┌───────────────────┐
                                   │  api.xingziwenhua  │
                                   │  .com              │
                                   │  (星子助推后端)      │
                                   └───────────────────┘

기술 스택

런타임: Node.js >= 18 (네이티브 fetch 사용)
MCP SDK: @modelcontextprotocol/sdk
파라미터 검증: zod (MCP SDK 내장 의존성)
전송 프로토콜: stdio (표준 입출력)
API 통신: HTTPS REST, JSON 형식

인증 메커니즘

Xingzi API는 비표준 인증 방식을 사용합니다 (H5 앱 리버스 엔지니어링을 통해 발견):

// 不是标准的 Authorization: Bearer <token>
// 而是三个自定义 HTTP headers:
headers: {
  "token": "<JWT>",      // 登录返回的 token
  "plt": "h5",           // 平台标识，固定值
  "user_id": "<number>"  // 用户 ID
}

토큰 유효기간은 24시간이며, MCP는 만료 전 자동으로 재로그인합니다.

금액 처리

API 내부에서는 '분(分)' 단위를 사용합니다 (예: 500 = 5.00 위안). MCP 도구 레벨에서는 **'위안(元)'**을 통일하여 사용하며, 내부적으로 자동 변환됩니다.

결제 프로세스

결제는 위챗 JSAPI 결제를 사용하며, 위챗 브라우저 환경(WeixinJSBridge)이 필요합니다. MCP는 직접 결제를 시작할 수 없으므로 결제 페이지 URL을 생성합니다:

https://m.xingziwenhua.com/spages/material/batchpay?id={task_id}
https://m.xingziwenhua.com/spages/material/batchpay?id={task_id}&to_user_id={koc_id}

사용자가 위챗에서 해당 링크를 열어 결제를 완료할 수 있습니다. 결제 페이지에서 금액 수정 및 보상 설명 작성이 가능합니다.

API 리버스 엔지니어링 노트

본 MCP의 모든 API 엔드포인트는 Xingzi Zhutui H5 앱(m.xingziwenhua.com)을 리버스 엔지니어링하여 획득했으며, 플랫폼에서 제공하는 공식 API 문서는 없습니다.

리버스 엔지니어링 방법

Puppeteer로 모바일 브라우저를 시뮬레이션하여 H5 앱 로그인
XHR 요청을 가로채어 API 호출 관찰 (표준 Bearer 인증이 아닌 커스텀 헤더 사용)
webpack chunk JS를 분석하여 모든 API 경로 추출
엔드포인트를 하나씩 테스트하여 파라미터 및 반환 형식 확인

주요 발견 사항

발견 사항	상세 내용
인증 방식	커스텀 헤더 `token` + `plt` + `user_id` 사용, `Authorization: Bearer` 아님
검토 인터페이스 파라미터	필드명 `is_pass` (언더스코어), `isPass` (카멜케이스) 아님 — Java Spring 역직렬화 요구사항
금액 단위	'분', 1위안 = 100
결제 제한	반드시 위챗 JSAPI 필요, 순수 API로 완료 불가
채널 ID	Xingzi 대행 = 188
파일 업로드	프론트엔드에서 COS로 직접 업로드, API 레벨에서는 업로드된 URL만 수신

검증된 API 엔드포인트

POST /c/user/login                               — 手机号+密码登录
GET  /c/user/detail                              — 用户信息
GET  /c/channel/list-available                   — 可用推广频道
POST /c/fodder/material/instead/publish           — 发布素材任务
GET  /c/fodder/material/instead/list              — 素材列表
GET  /c/fodder/material/instead/materialInfo      — 素材详情
POST /c/fodder/material/instead/del               — 删除素材
GET  /c/fodder/material/instead/postback/list     — 回执列表
POST /c/fodder/material/instead/postbackAudit     — 审核回执
GET  /c/fodder/material/instead/unpaidAward/list  — 待打款列表
POST /c/fodder/material/instead/batch/pay/reward  — 批量打款 (需微信)
GET  /c/withdraw/wallet                          — 钱包余额

결과물 상태 코드 (status)

값	의미
1	수락 완료, 결과물 미제출
2	결과물 제출 완료, 검토 대기
3	검토 승인

FAQ

Q: 소재 파일은 어떻게 업로드하나요?

MCP의 publish_task는 로컬 파일 경로가 아닌 파일 URL(공개적으로 접근 가능한 링크)을 받습니다. 파일을 먼저 파일 호스팅 서비스(텐센트 클라우드 COS, 알리바바 OSS, Qiniu, GitHub 등)에 업로드한 후 URL을 MCP에 전달해야 합니다.

Xingzi H5 앱 자체는 프론트엔드에서 텐센트 클라우드 COS로 직접 업로드하지만, 업로드 인터페이스가 프론트엔드 SDK에 바인딩되어 있어 순수 API 호출로는 불가능합니다.

Q: 왜 MCP 내에서 직접 결제를 완료할 수 없나요?

Xingzi의 결제는 위챗 JSAPI 결제를 사용하며, 위챗 브라우저 내에서 WeixinJSBridge.invoke('getBrandWCPayRequest', ...)를 호출해야 합니다. 이는 위챗 페이의 기술적 제한이며 MCP의 제한이 아닙니다. MCP는 결제 페이지 링크를 생성하며, 위챗에서 열어 결제할 수 있습니다.

Q: 하나의 작업에 여러 소재 파일을 올릴 수 있나요?

네. files 파라미터는 배열이며 여러 URL을 지원합니다 (최대 50개). 지원 형식: gif, jpg, jpeg, png, word, txt, pdf, mp4.

Q: 검토 거절 시 소재는 어떻게 되나요?

거절 시 해당 KOC의 수락 권한이 해제되어 다른 KOC가 수락할 수 있게 됩니다. 거절 사유(reject_reason)를 작성하면 KOC도 확인할 수 있습니다.

Q: 토큰이 만료되면 어떻게 하나요?

신경 쓰지 않으셔도 됩니다. MCP가 토큰 만료 전 자동으로 계정 비밀번호를 사용하여 재로그인합니다. 토큰 유효기간은 24시간입니다.

Q: 여러 계정을 동시에 사용할 수 있나요?

하나의 MCP 인스턴스는 하나의 계정에 대응합니다. 여러 계정이 필요한 경우, MCP 설정에 여러 서버를 추가하고 이름을 다르게 지정하여 구분할 수 있습니다:

{
  "mcpServers": {
    "xingzi-account1": {
      "command": "npx",
      "args": ["-y", "xingzi-mcp"],
      "env": { "XINGZI_MOBILE": "手机号1", "XINGZI_PASSWORD": "密码1" }
    },
    "xingzi-account2": {
      "command": "npx",
      "args": ["-y", "xingzi-mcp"],
      "env": { "XINGZI_MOBILE": "手机号2", "XINGZI_PASSWORD": "密码2" }
    }
  }
}

Q: 단가는 얼마가 적당한가요?

작업 복잡도에 따라 다릅니다. 최소 5위안을 권장하며, 5위안 미만은 거의 수락하지 않습니다. 자세한 내용은 가격 참고를 확인하세요.

Q: 결제 페이지에서 금액을 수정할 수 있나요?

네. pay_reward로 생성된 링크를 열면 각 KOC의 금액을 수동으로 수정할 수 있습니다. 예를 들어 특정 KOC의 결과물이 매우 좋다면 더 많은 보상을 줄 수 있습니다. 또한 '보상 설명'을 작성하면 KOC도 확인할 수 있습니다.

Q: 이 MCP와 Xingzi Zhutui 앱은 어떤 관계인가요?

Xingzi Zhutui는 트윗, 단편 드라마, 소설 등 다양한 홍보 업무를 포함하는 종합 KOC 홍보 플랫폼입니다. '소재 대행'은 그중 하나의 독립적인 제품 모듈입니다. 본 MCP는 소재 대행의 광고주 작업만 캡슐화했으며, Xingzi Zhutui의 다른 기능(키워드, 팀 관리, 수익 통계 등)은 포함하지 않습니다.

Q: 안전한가요? 계정 비밀번호는 어디에 저장되나요?

환경 변수 방식: 비밀번호는 로컬 MCP 설정 파일에 저장되며, Xingzi API 외의 어떤 곳으로도 전송되지 않습니다.
수동 로그인 방식: 비밀번호는 해당 세션에서만 사용됩니다.
MCP 코드는 완전히 오픈 소스이므로 직접 감사할 수 있습니다.

Changelog

3.0.0 (2026-04-06)

전체 엔드투엔드 프로세스 검증 완료
코드 및 문서 전면 정리
GitHub 배포

2.1.0

pay_reward에서 1인/전체 선택 결제 지원, koc_user_id 파라미터 지원
결제 링크에서 to_user_id 필터링 지원

2.0.1

audit_postback 파라미터 수정: is_pass ( isPass 아님), claim_id + postback_id ( material_id + id 아님)

2.0.0

소재 대행 전용으로 리팩토링, Xingzi Zhutui의 관련 없는 기능 제거
도구를 21개에서 11개로 간소화
기본값 최적화: 채널 Xingzi 대행 고정, 일반 소재, 고정 단가, 공개 설정
금액 단위를 '분'에서 '위안'으로 변경
guide 사용 가이드 도구 추가

1.0.0

초기 버전, Xingzi Zhutui 전체 API 캡슐화 포함

License

MIT