substack-mcp

Un servidor del Protocolo de Contexto de Modelo (MCP) para Substack. Permite a Claude Code crear borradores, subir imágenes, establecer miniaturas de portada, programar y publicar entradas en tu publicación de Substack.

Construido sobre python-substack. Utiliza la API interna de Substack (no existe una API pública de publicación). No está afiliado a Substack Inc.

Herramientas

Requeridas

• create_draft(title, content_markdown, subtitle?, audience?) — Crea un nuevo borrador a partir de Markdown.

• update_draft(post_id, title?, subtitle?, content_markdown?, audience?) — Edita un borrador existente.

• upload_image(image_path) — Sube un archivo local o una URL remota a la CDN de Substack, devolviendo la URL.

• publish_draft(post_id, send_email?, share_automatically?) — Publica inmediatamente. send_email alterna el envío por correo electrónico.

Recomendadas

• schedule_draft(post_id, iso_datetime) — Programa una publicación para una fecha/hora futura (ISO 8601).

• unschedule_draft(post_id) — Cancela una publicación programada.

• set_cover_image(post_id, image_url) — Establece la miniatura de portada (desde la URL de upload_image).

Utilidad

• list_drafts(limit?) — Lista los borradores recientes.

• get_draft(post_id) — Obtiene el cuerpo completo de un borrador.

• delete_draft(post_id) — Eliminación permanente.

Configuración

# 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

Reinicia Claude Code, luego /mcp debería mostrar substack-mcp como connected.

Cómo funciona la autenticación

Por defecto, substack-mcp-setup lee la cookie substack.sid directamente de tu sesión de Chrome existente a través de pycookiecheat. Substack no puede saber que algo fue automatizado porque nada lo fue: es la misma sesión que ya estás usando.

macOS solicitará una vez el acceso al Llavero ("Chrome Safe Storage"). Haz clic en "Siempre permitir" para que no vuelva a preguntar la próxima vez.

Compatible con: Chrome, Brave, Edge, Chromium, Vivaldi, Opera.

Modos de respaldo

# 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

Los tokens se almacenan en ~/Library/Application Support/substack-mcp/config.json con permisos 0600.

Seguridad

La cookie substack.sid es equivalente a una contraseña: cualquiera que la tenga tiene acceso total a la cuenta (publicar entradas, editar facturación, etc.). Trátala como tal.

Dónde reside el token

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

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

• O mediante variables de entorno: SUBSTACK_PUBLICATION_URL + SUBSTACK_SESSION_TOKEN (las variables de entorno son heredadas por los procesos hijos; ten cuidado al generar subprocesos)

El .gitignore excluye config.json; nunca lo subas al repositorio. El MCP también escribe un archivo de cookie temporal mediante tempfile.mkstemp (modo 0600) y lo elimina en un bloque finally — consulta auth.py:write_cookie_file.

Si un token se filtra

1. Cierra sesión en todas las sesiones: Substack → Configuración → Seguridad → "Cerrar sesión en todas las sesiones". Esto invalida cada substack.sid existente inmediatamente.

2. Vuelve a iniciar sesión en Substack en tu navegador.

3. Vuelve a ejecutar substack-mcp-setup para capturar la nueva cookie.

Seguridad en la carga de imágenes

upload_image solo acepta:

• URLs HTTP(S), o

• Archivos locales con extensiones de imagen (.png, .jpg, .jpeg, .gif, .webp, .heic, .heif) que no estén bajo rutas sensibles del sistema (/etc, /System, ~/.ssh, ~/.aws, ~/Library/Keychains, etc.)

Esto protege contra que un asistente sea engañado (mediante inyección de prompts en el contenido obtenido) para subir, por ejemplo, una clave privada SSH a la CDN de Substack.

Limitación conocida: La sintaxis de imagen Markdown ![alt](path) dentro de create_draft es procesada por python-substack y omite esta validación. Si pasas Markdown no confiable, desinfecta primero las rutas de las imágenes.

Dependencias

Las versiones están fijadas con ~= (lanzamiento compatible, sin cambios mayores). La actualización de python-substack en particular debe ser revisada: se comunica con la API privada de Substack y vive fuera de la superficie oficial de Substack.

Notas

• audience acepta: everyone (por defecto), only_paid, founding, only_free.

• La sintaxis de imagen Markdown ![alt](path/or/url) sube automáticamente archivos locales cuando llamas a create_draft.

• La imagen de portada (establecida mediante set_cover_image) es la que aparece en la página de inicio de tu publicación y en las publicaciones en redes sociales. Si no estableces una explícitamente, Substack normalmente utiliza la primera imagen del cuerpo.