weixin-articles-mcp

위챗(微信) 공식 계정 기사를 읽기 위한 MCP 서버로, 네이티브 멀티모달 출력을 지원합니다. 이미지와 비디오 키프레임이 URL이 아닌 콘텐츠 블록으로 반환됩니다.

개인/연구용입니다. 이 도구는 공개적으로 접근 가능한 기사 URL만 읽으며, 어떠한 인증이나 봇 방지 조치도 우회하지 않습니다. 사용 전 면책 조항을 확인하십시오.

이 도구가 필요한 이유

LLM을 위해 위챗 기사를 읽는 다른 도구들은 이미지 URL 목록만 반환합니다. 이 경우 LLM이 실제로 이미지를 보려면 클릭해서 들어가야 하므로 추가적인 왕복 시간과 컨텍스트 비용이 발생합니다.

이 서버는 이미지 자체와 비디오 키프레임을 반환합니다. LLM이 사용자와 동일한 내용을 한 번에 볼 수 있습니다.

Related MCP server: WeChat Article Parser

주요 기능

• 📰 안정적인 위챗 스크래핑 — 순수 파이썬 httpx GET 사용, Rust 바이너리나 헤드리스 브라우저 불필요

• 🖼️ 네이티브 이미지 콘텐츠 — PNG/JPG를 MCP Image 블록으로 반환, GIF는 필터링, 기사당 최대 10개 제한

• 🎬 세 가지 임베드 유형에 대한 비디오 처리:

  • 위챗 공식 계정 네이티브 비디오 (<iframe data-mpvid="wxv_*">): 인라인 JS에서 mp4 추출, ffmpeg를 통해 8개의 균등 간격 키프레임 생성

  • 텐센트 비디오 (v.qq.com iframe): yt-dlp + ffmpeg 키프레임

  • 위챗 채널(视频号, <mp-common-videosnap>): 공개 batch_get_video_snap API를 통한 전체 메타데이터(재생 시간, 크기, 고해상도 커버, 전체 설명, 좋아요 수, 게시자 인증) + 커버 이미지. mp4 스트림은 위챗의 finder 프로토콜로 잠겨 있습니다. 아래 채널 mp4는 왜 안 되나요?를 참조하세요.

• 🕒 게시 시간 복구 — 다른 파서가 놓치는 var ct 유닉스 타임스탬프 추출

• 🪶 최소한의 설치 — pip install + 비디오용 선택적 ffmpeg; Chromium이나 Rust 불필요

설치

# Core (article + images)
pip install weixin-articles-mcp

# With video keyframe support
pip install "weixin-articles-mcp[video]"
brew install ffmpeg   # or apt install ffmpeg on Linux

설정

Claude Desktop / Claude Code

{
  "mcpServers": {
    "weixin-articles": {
      "command": "weixin-articles-mcp"
    }
  }
}

Cursor / Cline

동일한 JSON을 클라이언트의 MCP 서버 설정에 붙여넣으세요.

사용법

설정이 완료되면 위챗 기사 URL을 대화창에 붙여넣기만 하면 됩니다:

Read https://mp.weixin.qq.com/s/cexkyzQBRDG3uIF6g5cEbQ

LLM은 다음을 받게 됩니다:

• 기사 메타데이터 (제목, 계정, 게시 시간, 커버 URL)

• 마크다운 형식의 전체 기사 본문

• 모든 인라인 PNG/JPG 이미지를 네이티브 이미지 콘텐츠 블록으로 제공

• 각 비디오에 대해 8개의 키프레임 이미지

도구 참조

read_article(url: str) -> list[content_block]

MCP 콘텐츠 블록 목록을 반환합니다:

• [0] — 텍스트 블록: 메타데이터 + 기사 본문 마크다운

• [1..N] — 이미지 블록: 기사 이미지 (최대 10개, GIF 필터링됨)

• 각 비디오(최대 3개)에 대해:

  • 위챗 네이티브 또는 텐센트: 텍스트 마커 1개 + 키프레임 이미지 블록 8개

  • 위챗 채널: 텍스트 마커 1개(재생 시간, 크기, 좋아요 수, 게시자, 설명 포함) + 고해상도 커버 이미지 블록 1개

실패 시 Error:로 시작하는 단일 텍스트 블록을 반환합니다.

로드맵

• [x] 봇 방지 처리가 포함된 위챗 기사 가져오기

• [x] 네이티브 이미지 콘텐츠 블록

• [x] 위챗 공식 계정 네이티브 비디오 키프레임 추출

• [x] 텐센트 비디오 키프레임 추출

• [x] 공개 API를 통한 위챗 채널(视频号) 메타데이터 강화

• [ ] faster-whisper를 통한 ASR 자막 (네이티브 + 텐센트 비디오용)

• [ ] 읽은 기사 전체 텍스트 검색

• [ ] 계정 구독 / 새 기사 알림

채널 mp4는 왜 안 되나요?

간단히 말해, 기사 내의 위챗 채널(视频号) 비디오는 의도적으로 다운로드 가능한 mp4 스트림을 공개 웹 접근에 노출하지 않습니다. mp4는 위챗의 finder 프로토콜 내부에 존재하며, 이는 (a) 로그인된 위챗 클라이언트 세션, (b) finder 전용 암호화(mp4의 첫 128KB는 고정 키로 XOR 암호화됨), (c) 네트워크 수준에서 위챗 PC 클라이언트의 스트림 가로채기가 필요합니다.

시중에 나와 있는 모든 오픈 소스 위챗 채널 다운로더(ltaoo/wx_channels_download, qiye45/wechatVideoDownload, putyy/res-downloader, KingsleyYau/WeChatChannelsDownloader 등)는 MITM HTTPS 프록시 + 위챗 PC 클라이언트 + 루트 CA 설치를 통해 이 문제를 해결합니다. 해당 모델은 MCP 서버가 작동하는 방식(클라이언트 없음, 사용자 상호작용 없음, 관리자 설치 없음)과 근본적으로 호환되지 않습니다.

대신 우리는 위챗의 공개 batch_get_video_snap API(쿠키나 세션 불필요)를 호출하여 LLM에 최선의 대안인 고해상도 커버 이미지, 전체 설명, 재생 시간, 크기, 좋아요 수, 게시자 인증 정보를 제공합니다. 대부분의 사용 사례(기사 읽기 및 요약)에서 이는 비디오의 핵심 내용을 전달하기에 충분합니다.

mp4 파일이 반드시 필요한 경우, 이 MCP와 함께 위의 전용 도구 중 하나를 설치하여 상호 보완적으로 사용하십시오.

아키텍처

src/weixin_articles_mcp/
├── server.py     # FastMCP entrypoint, tool registration
├── fetcher.py    # httpx GET with browser UA
├── parser.py     # WeChat DOM extraction (BeautifulSoup + lxml)
├── markdown.py   # HTML → Markdown (markdownify subclass)
└── media.py      # Image download + video download/keyframe extraction

기여

PR을 환영합니다. 특히 다음 분야에 대한 도움을 기다립니다:

• 위챗 채널(视频号) URL 처리

• 덜 일반적인 게시자의 템플릿 변형에 대한 복원력

• 더 많은 테스트 픽스처 (다양한 기사 스타일)

이슈 열기: https://github.com/jj-cheng25/weixin-articles-mcp/issues

면책 조항

이 도구는 개인, 교육 및 연구용으로만 제공됩니다.

이 도구가 수행하는 작업:

• 표준 브라우저 User-Agent를 사용하여 공개적으로 접근 가능한 위챗 기사 URL(mp.weixin.qq.com/s/...)을 읽습니다. 이는 웹 브라우저를 사용하는 모든 사용자가 볼 수 있는 동일한 콘텐츠입니다.

• 빈 인증 필드를 허용하는 공개 위챗 API 엔드포인트만 호출합니다(즉, 로그인 없이 접근 가능하도록 위챗이 설계함).

• 도구가 대량 크롤러로 재사용되는 것을 방지하기 위해 요청 간 기본 1초 최소 간격을 강제합니다.

이 도구가 수행하지 않는 작업:

• 쿠키, 로그인 세션 또는 어떠한 형태의 사용자 자격 증명도 사용하지 않습니다.

• 기술적 보호, 봇 방지 조치 또는 암호화된 스트림을 우회하지 않습니다(예: 위챗 채널 mp4는 의도적으로 지원하지 않음 — 채널 mp4는 왜 안 되나요? 참조).

• 위챗의 프로토콜 수준 보호를 복호화, 리버스 엔지니어링 또는 우회하지 않습니다.

• 즉각적인 응답 외에 가져온 콘텐츠를 저장, 캐시 또는 재배포하지 않습니다.

사용자 책임:

• 이 도구를 사용할 때 위챗의 서비스 약관을 준수하십시오. 공개적으로 접근 가능한 기사의 개인/연구용 사용은 일반적으로 콘텐츠가 소비되도록 의도된 방식과 일치하지만, 대량 스크래핑이나 상업적 재배포는 그렇지 않을 가능성이 높습니다.

• 가져온 콘텐츠의 저작권을 존중하십시오. 기사 콘텐츠는 원저작자와 게시자의 재산으로 남으며, 이 도구는 인라인 처리를 위해 LLM으로 가져와 전달할 뿐입니다.

• mp.weixin.qq.com에 과부하를 주지 마십시오. 인간이 읽는 속도로 사용하십시오. 기본 속도 제한은 보수적으로 설정되어 있지만, 환경 설정에서 WEIXIN_FETCH_INTERVAL_S=2.0(또는 그 이상)으로 설정하여 더 엄격하게 제한할 수 있습니다.

이 프로젝트의 저자와 기여자는 오용으로 인해 발생하는 모든 책임에 대해 면책됩니다. 이 소프트웨어를 사용함으로써 귀하는 귀하의 사용이 관련 법률 및 연결된 서비스의 서비스 약관을 준수하도록 보장할 모든 책임을 집니다.

라이선스

MIT — LICENSE 참조.