bearblog-mcp-server 0.3.0

MCP server for Bear Blog integration

Bear Blog MCP Server

A Model Context Protocol (MCP) server for interacting with Bear Blog programmatically. This allows AI assistants like Claude to manage your Bear Blog posts directly.

Features

Post Management

• List Posts: Get all your blog posts with metadata
• Read Posts: Retrieve full post content including title, slug, and markdown body
• Create Posts: Write new blog posts (as drafts or published)
• Update Posts: Edit existing posts
• Delete Posts: Permanently remove posts
• Publish/Unpublish: Toggle post publication status
• Post Attributes: Full support for Bear Blog post attributes including alias, canonical_url, meta_description, meta_image, lang, tags, is_page, and make_discoverable

Page Management

• List Pages: Get all your static pages with metadata
• Read Pages: Retrieve full page content
• Create Pages: Create new pages (About, Contact, etc.)
• Update Pages: Edit existing pages
• Delete Pages: Permanently remove pages
• Publish/Unpublish Pages: Toggle page publication status
• Page Attributes: Same attribute support as posts

Blog Settings

• Get Settings: Retrieve all blog configuration
• Update Settings: Modify blog subdomain, language, analytics, and advanced options

Home Page Content

• Get Home Page: Retrieve blog title, favicon, meta description, meta image, and landing page content
• Update Home Page: Customize blog title, favicon, meta description, meta image, and home page markdown

Navigation Management

• Get Navigation: Retrieve navigation menu links in markdown format
• Update Navigation: Customize navigation menu with markdown-formatted links

Theme and Style Management

• List Themes: Get all available pre-built themes (30+ community themes)
• Get Styles: Retrieve current custom CSS
• Update Styles: Modify custom CSS to customize appearance
• Apply Theme: Apply a pre-built theme (WARNING: overwrites custom CSS)

Installation

Quick Start (Recommended)

pipx install bearblog-mcp-server

Or with uv:

uv pip install bearblog-mcp-server

For Development

Clone the repository and install in editable mode:

git clone https://github.com/rmunoz33/bearblog-mcp.git
cd bearblog-mcp
uv pip install -e .

Configuration

Session Cookies

The MCP server authenticates using session cookies from your browser. To get them:

1. Log into bearblog.dev in your browser
2. Open DevTools → Application → Cookies → bearblog.dev
3. Copy the sessionid and csrftoken values

Environment Variables

• BEAR_BLOG_SESSION_ID - Your sessionid cookie value (required)
• BEAR_BLOG_CSRF_TOKEN - Your csrftoken cookie value (required)
• BEAR_BLOG_SUBDOMAIN - Your blog's subdomain (required, e.g., "myblog" for myblog.bearblog.dev)
• BEAR_BLOG_BASE_URL - Base URL (default: https://bearblog.dev)

Note: Session cookies expire every ~90 days. When they expire, log into Bear Blog again in your browser and update the cookie values.

Usage

With Claude Code

Add to your Claude Code MCP settings (.mcp.json in your project or ~/.claude.json globally):

{
  "mcpServers": {
    "bearblog": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "bearblog-mcp-server", "bearblog-mcp"],
      "env": {
        "BEAR_BLOG_SESSION_ID": "your_session_id",
        "BEAR_BLOG_CSRF_TOKEN": "your_csrf_token",
        "BEAR_BLOG_SUBDOMAIN": "your_subdomain"
      }
    }
  }
}

After editing the config, restart Claude Code and verify with the /mcp command.

Standalone

Run the server directly:

BEAR_BLOG_SESSION_ID=xxx BEAR_BLOG_CSRF_TOKEN=yyy BEAR_BLOG_SUBDOMAIN=blog \
  bearblog-mcp

Available Tools

Post Tools

• bear_list_posts - List all blog posts
• bear_get_post - Get a specific post by ID
• bear_create_post - Create a new post
• bear_update_post - Update an existing post
• bear_delete_post - Delete a post permanently
• bear_publish_post - Toggle publish status

Page Tools

• bear_list_pages - List all pages
• bear_get_page - Get a specific page by ID
• bear_create_page - Create a new page
• bear_update_page - Update an existing page
• bear_delete_page - Delete a page permanently
• bear_publish_page - Toggle page publish status

Settings Tools

• bear_get_blog_settings - Get current blog configuration
• bear_update_blog_settings - Update blog settings

Home Page Tools

• bear_get_home_page - Get blog title, favicon, meta description, meta image, and content
• bear_update_home_page - Update blog title, favicon, meta description, meta image, and content

Navigation Tools

• bear_get_navigation - Get navigation menu links
• bear_update_navigation - Update navigation menu with markdown links

Theme and Style Tools

• bear_list_themes - List all available pre-built themes
• bear_get_styles - Get current custom CSS
• bear_update_styles - Update custom CSS
• bear_apply_theme - Apply a pre-built theme (WARNING: overwrites custom CSS)

Resources

• bear://posts - Formatted list of all posts
• bear://post/{id} - Individual post content
• bear://pages - Formatted list of all pages
• bear://page/{id} - Individual page content

Premium Features

This MCP server was developed and tested using a free Bear Blog account. Some Bear Blog features require a Bear Blog Pro subscription ($5/month or $49/year) and are not currently implemented:

• Email List Management: Subscriber capture and newsletter functionality
• Media Upload: Direct file and image uploading via MCP tools
• Custom Domains: Domain configuration tools
• Advanced Analytics: Detailed traffic and engagement metrics

If you have a Bear Blog Pro account and would like these features added, please open an issue on GitHub or reach out to discuss implementation.

Testing

Run the test scripts to verify functionality:

# Test post management
uv run python tests/test_tools.py

# Test page management
uv run python tests/test_pages.py

# Test post/page attributes (meta_description, tags, etc.)
uv run python tests/test_attributes.py

Development

See research/ directory for API exploration scripts and API_FINDINGS.md for endpoint documentation.

License

MIT

Credits

Built with FastMCP - The fast, Pythonic way to build MCP servers.