halo

Halo MCP Server for Halo integrates AI-powered blog management into your Halo installation. It exposes a set of tools that let you create, edit, publish, and organize posts, categories, tags, and attachments, all through natural language prompts or explicit tool calls. With the MCP you can also leverage AI prompts to assist with writing, SEO optimization, translation, and content refinement, enabling seamless collaboration between Halo and AI assistants like Claude or Cursor. To get started, configure the HALO_BASE_URL and HALO_TOKEN in your environment, then run the Halo MCP Server so your client (e.g., Claude Desktop) can reach Halo through the MCP bridge. The server supports a suite of 30+ management tools and 10 prompts that help guide content creation and workflow automation. Once running, you can interact with Halo via natural-language requests such as “请写一篇关于 X 的文章并发布” or explicit prompts like create_post, publish_post, and list_categories, depending on your client configuration. The MCP layer handles authentication, routing, and orchestration between the client and Halo, enabling a more conversational blogging experience while preserving Halo’s native capabilities.

Prerequisites:

• Python 3.10 or newer
• Halo blog system accessible (Halo 2.21+ recommended)
• A client that supports MCP (e.g., Claude Desktop) configured to point at the MCP server

Option A: From source (development)

# 1. Clone the repository
git clone https://github.com/Huangwh826/halo-mcp-server.git
cd halo-mcp-server

# 2. Create and activate a virtual environment
python -m venv venv
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# 3. Install in editable mode
pip install -e .

Option B: Install via pip (stable)

pip install halo-mcp-server

Configuration (required for Claude Desktop or other MCP clients):

1. Retrieve Halo access token following Halo's instructions.
2. Create or edit the MCP client config to point to the Halo MCP Server (see example below).

{
  "mcpServers": {
    "halo-mcp-server": {
      "command": "python",
      "args": [
        "-m",
        "halo_mcp_server"
      ],
      "env": {
        "HALO_BASE_URL": "your_halo_base_url_here",
        "HALO_TOKEN": "your_halo_token_here"
      }
    }
  }
}

3. Start the MCP server (depending on your setup). For the Python backend shown here, ensure the environment variables are set and run the designated command (see mcp_config).
4. In Claude Desktop (or another client), point the config to halo-mcp-server and test a command like listing articles or creating a post.

Tips and common issues:

• Ensure HALO_BASE_URL uses a full URL including http(s):// and the Halo token has sufficient permissions to manage posts, categories, and attachments.
• If using a virtual environment, set the python path in the CLI or client config to the virtual environment’s Python executable.
• Restart your MCP client after making changes to the server configuration or environment variables.
• Validate API reachability by hitting the Halo base URL with the provided token from the MCP server environment.
• If you encounter SSL or certificate issues when connecting to Halo, verify network accessibility and consider using a trusted certificate or proper HTTPS configuration on your Halo instance.