blogger-mcp-toolkit

A universal MCP (Model Context Protocol) server providing complete access to the Google Blogger API v3, permanent Base64 media embedding, and lightweight summary listing modes.

Interact seamlessly with Blogger blogs, posts, pages, comments, media, and user profiles directly from your favorite AI assistant or MCP-enabled client (such as Claude Code, Claude Desktop, Cursor, Zed, Windsurf, or Antigravity CLI).

---

📑 Table of Contents

• Features
• Quick Start & Installation
• Google Cloud Console Setup
• Manual Setup
• Environment Variables
• Available Tools (29)
• MCP Client Configuration
• License

---

🌟 Features

• 100% Blogger API v3 Coverage + Media & Search Extensions: 29 MCP tools for full management of blogs, posts, pages, comments, media, and users.
• Remote-Friendly Interactive OAuth (npx blogger-mcp-auth): Standalone authentication CLI supporting local browser redirect AND manual code copy-pasting for remote/SSH/Docker environments.
• Strict BLOGGER_* Environment Schema: Clean, standardized configuration using BLOGGER_CLIENT_ID, BLOGGER_CLIENT_SECRET, BLOGGER_REFRESH_TOKEN, and BLOGGER_API_KEY.
• Permanent Base64 Image Embedding (blogger_media_to_base64): Convert local images (.png, .jpg, .jpeg, .webp, .gif, .svg) into Base64 Data URIs with zero external CDN dependencies, ensuring your images never expire.
• Lightweight Listing Mode (summaryOnly): Omit heavy HTML post content on list, search, and searchByLabel endpoints to drastically reduce JSON response sizes (from >50KB down to ~2KB) and prevent payload truncation.
• Dedicated Label Search (blogger_posts_searchByLabel): Quick filtering of posts by tag/label.
• Automatic HTML Markdown Cleaner: Cleans raw Markdown code fences (e.g. html ... ) before publishing posts or pages to Blogger.

---

🚀 Quick Start & Installation

Step 1: Acquire your Blogger Refresh Token

Run the interactive authentication tool directly in your terminal:

npx blogger-mcp-auth

• Interactive Prompt: Enter your BLOGGER_CLIENT_ID and BLOGGER_CLIENT_SECRET when prompted.
• Browser Authentication: Authorize the app in your browser. (If working over SSH/remote container, simply copy-paste the redirected URL or authorization code back into the terminal!)
• Token Output: Copy the generated BLOGGER_REFRESH_TOKEN displayed in green.

---

Step 2: Install across your AI assistants with add-mcp

Install and configure automatically across all your AI assistants (Claude Code, Cursor, Zed, Windsurf, VS Code, etc.) in one single command:

npx add-mcp blogger-mcp-toolkit \
  --env BLOGGER_CLIENT_ID=your-client-id.apps.googleusercontent.com \
  --env BLOGGER_CLIENT_SECRET=your-client-secret \
  --env BLOGGER_REFRESH_TOKEN=your-refresh-token

---

⚙️ Google Cloud Console Setup

To communicate with the Blogger API, you need OAuth2 credentials:

1. Create a Project: Go to Google Cloud Console, click New Project, and name it (e.g., Blogger MCP).
2. Enable Blogger API v3: Go to APIs & Services > Library, search for Blogger API v3, and click Enable.
3. Configure OAuth Consent Screen:
   • Go to APIs & Services > OAuth consent screen.
   • Choose External, fill in required support email fields.
   • Under Test users, add your own Google email address (Crucial if your app is in "Testing" status!).
4. Create Credentials:
   • Go to APIs & Services > Credentials > + CREATE CREDENTIALS > OAuth client ID.
   • Select Web application (or Desktop app).
   • Add Authorized redirect URI: http://localhost:3000/oauth2callback (or port 3001/3002).
   • Copy your Client ID and Client Secret.

---

📦 Manual Setup

# Clone the repository
git clone https://github.com/RadouaneElarfaoui/blogger-mcp-toolkit.git
cd blogger-mcp-toolkit

# Install dependencies & build
npm install
npm run build

# Generate Refresh Token locally
cp .env.example .env
npm run auth

---

🌍 Environment Variables

blogger-mcp-toolkit exclusively uses the following BLOGGER_* environment variables:

Variable	Description	Required
BLOGGER_CLIENT_ID	OAuth2 Client ID from Google Cloud Console	Yes
BLOGGER_CLIENT_SECRET	OAuth2 Client Secret from Google Cloud Console	Yes
BLOGGER_REFRESH_TOKEN	OAuth2 Refresh Token (generated via npx blogger-mcp-auth)	Yes
BLOGGER_API_KEY	Optional API key for read-only access	No

---

🛠️ Available Tools (29)

<details open> <summary><strong>📝 Blogs (3 tools)</strong></summary>

Tool Name	Description
blogger_blogs_get	Get blog metadata by blog ID
blogger_blogs_getByUrl	Get blog metadata by its URL
blogger_blogs_listByUser	List blogs for a user

</details>

<details open> <summary><strong>📄 Posts (11 tools)</strong></summary>

Tool Name	Description
blogger_posts_list	List posts for a blog (supports summaryOnly mode to strip heavy HTML content)
blogger_posts_get	Get a post by ID
blogger_posts_getByPath	Get a post by its URL path
blogger_posts_search	Search posts by query string (supports summaryOnly mode)
blogger_posts_searchByLabel	Filter posts by a label/tag (supports summaryOnly mode)
blogger_posts_insert	Create a new post (automatically strips raw Markdown HTML code block wrappers)
blogger_posts_update	Full update of a post
blogger_posts_patch	Partial update of a post
blogger_posts_delete	Delete a post
blogger_posts_publish	Publish a draft post
blogger_posts_revert	Revert a published post to draft

</details>

<details open> <summary><strong>📑 Pages (6 tools)</strong></summary>

Tool Name	Description
blogger_pages_list	List static pages for a blog
blogger_pages_get	Get a page by ID
blogger_pages_insert	Create a new static page (automatically strips raw Markdown HTML code block wrappers)
blogger_pages_update	Full update of a page
blogger_pages_patch	Partial update of a page
blogger_pages_delete	Delete a page

</details>

<details open> <summary><strong>💬 Comments (7 tools)</strong></summary>

Tool Name	Description
blogger_comments_list	List comments for a specific post
blogger_comments_listByBlog	List comments across all posts
blogger_comments_get	Get a specific comment
blogger_comments_approve	Approve a comment
blogger_comments_delete	Permanently delete a comment
blogger_comments_removeContent	Remove comment content
blogger_comments_markAsSpam	Mark a comment as spam

</details>

<details open> <summary><strong>🖼️ Media (1 tool)</strong></summary>

Tool Name	Description
blogger_media_to_base64	Convert a local image file (.png, .jpg, .jpeg, .webp, .gif, .svg) to an embedded Base64 Data URI with a ready-to-use Blogger <img> tag snippet for zero-dependency permanent embedding

</details>

<details open> <summary><strong>👤 Users (1 tool)</strong></summary>

Tool Name	Description
blogger_users_get	Get user profile information

</details>

---

🔌 MCP Client Configuration

Claude Desktop

Edit your claude_desktop_config.json:

{
  "mcpServers": {
    "blogger": {
      "command": "npx",
      "args": ["-y", "blogger-mcp-toolkit"],
      "env": {
        "BLOGGER_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "BLOGGER_CLIENT_SECRET": "your-client-secret",
        "BLOGGER_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Cursor

Edit .cursor/mcp.json or Cursor MCP settings:

{
  "mcpServers": {
    "blogger": {
      "command": "npx",
      "args": ["-y", "blogger-mcp-toolkit"],
      "env": {
        "BLOGGER_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "BLOGGER_CLIENT_SECRET": "your-client-secret",
        "BLOGGER_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "blogger": {
      "command": "npx",
      "args": ["-y", "blogger-mcp-toolkit"],
      "env": {
        "BLOGGER_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "BLOGGER_CLIENT_SECRET": "your-client-secret",
        "BLOGGER_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Zed

Edit settings.json in Zed:

{
  "context_servers": {
    "blogger": {
      "command": {
        "path": "npx",
        "args": ["-y", "blogger-mcp-toolkit"]
      },
      "env": {
        "BLOGGER_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "BLOGGER_CLIENT_SECRET": "your-client-secret",
        "BLOGGER_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

---

📄 License

This project is licensed under the MIT License.