bearblog-mcp-server 0.2.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

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

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)

Install with pipx:

pipx install bearblog-mcp-server
playwright install chromium

Or with uv:

uv pip install bearblog-mcp-server
playwright install chromium

The playwright install chromium step downloads the Chromium browser (~160MB) that the MCP server uses to interact with Bear Blog. This only needs to be done once.

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 .
playwright install chromium

Configuration

Environment Variables

The MCP server requires Bear Blog credentials to be provided as environment variables:

• BEAR_BLOG_EMAIL - Your Bear Blog account email
• BEAR_BLOG_PASSWORD - Your Bear Blog account password
• BEAR_BLOG_SUBDOMAIN - Your blog's subdomain (e.g., "myblog" for myblog.bearblog.dev)
• BEAR_BLOG_BASE_URL - Base URL (default: https://bearblog.dev)
• BEAR_BLOG_STATE_PATH - Path to session state file (default: ~/.bearblog-session.json)

Note: For passwords with special characters, wrap them in single quotes in .env files (e.g., BEAR_BLOG_PASSWORD='p@ss$word'). Python-dotenv does not expand $ variables, so dollar signs are treated as literals.

Usage

With Claude Code

Add to your Claude Code MCP settings (~/.claude.json):

{
  "mcpServers": {
    "bearblog": {
      "type": "stdio",
      "command": "bearblog-mcp",
      "env": {
        "BEAR_BLOG_EMAIL": "[e-mail]",
        "BEAR_BLOG_PASSWORD": "your_password",
        "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_EMAIL=[e-mail] BEAR_BLOG_PASSWORD=pass 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

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.