---
name: bearletter
description: Work on the author's Bearletter blog through the Bearletter MCP server - write, preview and publish posts, pages and podcast episodes, edit the home page, menu and theme, and back up. Use when the user mentions Bearletter or their blog hosted on bearletter.com.
---

# Bearletter

Bearletter hosts the author's blog. A blog is a folder of plain text: Markdown posts in `posts/`, pages in `pages/`, podcast episodes in `podcast/`, site files with fixed names, a few components (lines starting with `::`), and one `styles.css`. A draft is a file with `publish: false`; edits to a published file wait as unpublished changes until they are published.

The format is documented at https://docs.bearletter.com/llms.txt (every page is Markdown). Read the pages you need before writing files, or call `get_blog_guide`.

## Connect

If the `bearletter` MCP tools are not available, add the remote MCP server `https://api.bearletter.com/mcp` (HTTP) to your configuration, the way your agent adds MCP servers. The author approves it in the browser the first time; there is no key. Then call `get_blog` and tell the author their blog's title and address.

## Rules

- The site files have fixed names: `home.md`, `nav.md`, `footer.md`, `post-header.md`, `post-footer.md`, `post-aside.md`, `social.md`, `blogroll.md`, `directories.md`, `redirects.md`, `podcast.md`, `styles.css`. Never rename them, move them or invent other site files. Only files under `posts/`, `pages/` and `podcast/` are yours to name.
- Read before you write, and pass back the `writeSeq` you read. If a save is refused as stale, read again and reapply the change.
- A refused save names the lines to fix. Fix those lines and try again; do not guess around the error.
- Anything public (publishing, saving a site file, changing the theme) goes live at once. Tell the author what will change and wait for a clear yes.
- For posts the author will review, write drafts (`create_draft`, `save_draft`) and let them publish; `save_blog_file` replaces what readers see.
- Images and audio come from the author's media library. Upload new files with `start_media_upload`, a direct HTTP PUT, then `finish_media_upload`; never send file bytes through other tools.

## Common tasks

**Write and publish a post.** `create_draft` with a title and Markdown body, show the author the text, `preview_file` for a link they can open, then on their yes `publish_file` (with `subdomain` the first time, when the blog has no address yet). Report the post's address.

**Edit a published post.** `read_blog_file` by id, `save_draft` with the whole new text (it becomes unpublished changes), `preview_file`, then `publish_file`. `discard_changes` drops the edits.

**Change the look.** `list_themes`, then `preview_styles` with a theme or a whole new `styles.css` and give the author the link. Only after they agree: `apply_theme` or `save_blog_file` for `styles.css`. Keep the first `:root` block of variables first, and add dark values in `@media (prefers-color-scheme: dark)`.

**Edit the menu or the home page.** `read_blog_file` (`nav.md`, `home.md`…), change it, show the diff, then `save_blog_file`.

**Add a podcast episode** (Pro). Upload the audio, then `create_draft` with kind `episode`, set `audio:` (and `duration:`) in its property block with `save_draft`, and publish it. The show's settings are in `podcast.md`.

**Back up.** Ask the author for a backup token (Settings › Apps & tokens) and follow https://docs.bearletter.com/api/backup.md; or use Download everything in the dashboard.
