Metadata-Version: 2.4
Name: bearblog-mcp-server
Version: 0.2.1
Summary: MCP server for Bear Blog integration
Author-email: Rocky Munoz <almostheresy@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/rockymunoz/bearblog-mcp-server
Project-URL: Repository, https://github.com/rockymunoz/bearblog-mcp-server
Keywords: mcp,bearblog,blog,model-context-protocol,claude,ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content :: Content Management System
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# Bear Blog MCP Server

[![PyPI version](https://badge.fury.io/py/bearblog-mcp-server.svg)](https://pypi.org/project/bearblog-mcp-server/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Model Context Protocol (MCP) server for interacting with [Bear Blog](https://bearblog.dev) 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)

```bash
pipx install bearblog-mcp-server
```

Or with `uv`:

```bash
uv pip install bearblog-mcp-server
```

### For Development

Clone the repository and install in editable mode:

```bash
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](https://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):

```json
{
  "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:

```bash
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](https://bearblog.dev/dashboard/upgrade/) ($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](https://github.com/rmunoz33/bearblog-mcp/issues) or reach out to discuss implementation.

## Testing

Run the test scripts to verify functionality:

```bash
# 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](https://github.com/jlowin/fastmcp) - The fast, Pythonic way to build MCP servers.
