substack-mcp

Substack용 모델 컨텍스트 프로토콜(MCP) 서버입니다. Claude Code가 Substack 간행물에서 초안 작성, 이미지 업로드, 커버 썸네일 설정, 예약 및 게시를 수행할 수 있게 합니다.

python-substack을 기반으로 구축되었습니다. Substack의 내부 API를 사용합니다(공개 게시 API는 존재하지 않음). Substack Inc.와는 관련이 없습니다.

도구

필수

• create_draft(title, content_markdown, subtitle?, audience?) — Markdown에서 새 초안을 생성합니다.

• update_draft(post_id, title?, subtitle?, content_markdown?, audience?) — 기존 초안을 수정합니다.

• upload_image(image_path) — 로컬 파일이나 원격 URL을 Substack의 CDN에 업로드하고 URL을 반환합니다.

• publish_draft(post_id, send_email?, share_automatically?) — 즉시 게시합니다. send_email은 이메일 발송 여부를 전환합니다.

권장

• schedule_draft(post_id, iso_datetime) — 향후 날짜/시간(ISO 8601)에 게시하도록 예약합니다.

• unschedule_draft(post_id) — 예약된 게시를 취소합니다.

• set_cover_image(post_id, image_url) — 커버 썸네일을 설정합니다(upload_image URL 사용).

유틸리티

• list_drafts(limit?) — 최근 초안을 나열합니다.

• get_draft(post_id) — 초안의 전체 본문을 가져옵니다.

• delete_draft(post_id) — 영구 삭제합니다.

설정

# 1. Install dependencies
uv pip install -e .

# 2. Make sure you're logged in to Substack in Chrome (or Brave/Edge) — that's it.

# 3. Save credentials — auto-detects your existing browser session
substack-mcp-setup

# 4. Register with Claude Code
claude mcp add substack-mcp --scope user -- /Users/$USER/substack/.venv/bin/substack-mcp

Claude Code를 재시작하면 /mcp에서 substack-mcp가 connected로 표시되어야 합니다.

인증 작동 방식

기본적으로 substack-mcp-setup은 pycookiecheat을 통해 기존 Chrome 세션에서 substack.sid 쿠키를 직접 읽습니다. Substack은 자동화 여부를 알 수 없습니다. 자동화된 것이 없기 때문입니다. 이미 사용 중인 동일한 세션을 사용합니다.

macOS는 키체인 액세스("Chrome Safe Storage")에 대해 한 번 확인을 요청합니다. 다음번에 다시 묻지 않도록 "항상 허용(Always Allow)"을 클릭하세요.

지원 브라우저: Chrome, Brave, Edge, Chromium, Vivaldi, Opera.

대체 모드

# Specific browser
substack-mcp-setup --from-browser brave

# Playwright-based (often blocked by Substack — use --chrome instead)
substack-mcp-setup --browser

# Manual paste from DevTools
substack-mcp-setup --manual

토큰은 0600 권한으로 ~/Library/Application Support/substack-mcp/config.json에 저장됩니다.

보안

substack.sid 쿠키는 비밀번호와 동일합니다. 이를 가진 사람은 누구나 전체 계정 액세스 권한(게시물 게시, 결제 정보 수정 등)을 가집니다. 따라서 비밀번호처럼 취급하십시오.

토큰 저장 위치

• macOS: ~/Library/Application Support/substack-mcp/config.json (모드 0600)

• Linux: ~/.config/substack-mcp/config.json (모드 0600)

• 또는 환경 변수 사용: SUBSTACK_PUBLICATION_URL + SUBSTACK_SESSION_TOKEN (환경 변수는 자식 프로세스에 상속되므로 하위 프로세스를 생성할 때 주의하십시오)

.gitignore는 config.json을 제외하므로 절대 커밋하지 마십시오. 또한 MCP는 tempfile.mkstemp(모드 0600)를 통해 임시 쿠키 파일을 작성하고 finally 블록에서 삭제합니다. auth.py:write_cookie_file을 참조하세요.

토큰이 유출된 경우

1. 모든 세션에서 로그아웃: Substack → 설정 → 보안 → "모든 세션에서 로그아웃". 이렇게 하면 기존의 모든 substack.sid가 즉시 무효화됩니다.

2. 브라우저에서 Substack에 다시 로그인합니다.

3. substack-mcp-setup을 다시 실행하여 새 쿠키를 캡처합니다.

이미지 업로드 안전성

upload_image는 다음만 허용합니다:

• HTTP(S) URL, 또는

• 민감한 시스템 경로(/etc, /System, ~/.ssh, ~/.aws, ~/Library/Keychains 등)에 있지 않은 이미지 확장자(.png, .jpg, .jpeg, .gif, .webp, .heic, .heif)를 가진 로컬 파일

이는 어시스턴트가 (가져온 콘텐츠의 프롬프트 주입을 통해) 속아서 SSH 개인 키 등을 Substack의 CDN에 업로드하는 것을 방지합니다.

알려진 제한 사항: create_draft 내의 Markdown 이미지 구문 ![alt](path)은 python-substack에 의해 처리되며 이 유효성 검사를 우회합니다. 신뢰할 수 없는 Markdown을 전달하는 경우 먼저 이미지 경로를 삭제(sanitize)하십시오.

종속성

버전은 ~=(호환 가능한 릴리스, 메이저 업데이트 없음)로 고정되어 있습니다. 특히 python-substack의 버전을 올릴 때는 주의해야 합니다. 이 라이브러리는 Substack의 비공개 API와 통신하며 Substack의 공식 인터페이스 외부에서 작동합니다.

참고

• audience 허용 값: everyone(기본값), only_paid, founding, only_free.

• Markdown 이미지 구문 ![alt](path/or/url)은 create_draft를 호출할 때 로컬 파일을 자동으로 업로드합니다.

• 커버 이미지(set_cover_image를 통해 설정)는 간행물 홈페이지와 소셜 공유 시 표시되는 이미지입니다. 명시적으로 설정하지 않으면 Substack은 일반적으로 본문의 첫 번째 이미지를 사용합니다.