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

Related MCP server: blogger-mcp

🌟 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:

• Option A (Official GitHub Release — Recommended for Latest Version):

  npx github:RadouaneElarfaoui/blogger-mcp-toolkit blogger-mcp-auth

• Option B (NPM Registry Release):

  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:

• Option A (Official GitHub Release — Recommended for Latest Version):

  npx add-mcp github:RadouaneElarfaoui/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

• Option B (NPM Registry Release):

  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:

🛠️ Available Tools (29)

🔌 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.