Halo

Halo MCP Server is a Python-based bridge that lets you manage your Halo blog with natural language through MCP clients. It enables AI assistants to create, edit, publish, and organize posts and related content, turning blog management into a conversational workflow.

How to use

You connect an MCP client (like Claude Desktop) to Halo MCP Server to manage your Halo blog using everyday language. Start by configuring the MCP client with your Halo server URL and API token, then ask questions or give commands such as creating a post, updating a draft, or listing categories. The system automatically routes your intent to the right tools and prompts, so you don’t need to memorize specific commands.

How to install

Prerequisites you need before installing are Python 3.10 or newer and a Halo blog system version 2.21 or newer. You also need MCP-compatible clients like Claude Desktop.

# 1) Ensure Python is available
python --version  # should be 3.10+

# 2) Install Halo MCP Server from source or via package manager
# From source (development):
# 1. Clone the repository
# git clone https://github.com/Huangwh826/halo_mcp_server.git
# 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 .

# Or install from PyPI (recommended for stable use)
pip install halo-mcp-server

# 4. Run the server (if running locally and not managed by a process manager)
python -m halo_mcp_server

If you installed via source, you can run the server with Python directly. If you installed from PyPI, use the same runtime entry point depending on how your environment handles Python packages.

Configuration and initial setup

You configure the client with the Halo base URL and an access token you obtain from Halo. Create a token with full management rights from Halo’s user center, then place the values into your MCP client configuration.

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

Security and tokens

Treat your Halo API token like a password. Do not expose it in public scripts or logs. When configuring the MCP client, store tokens securely and restrict token permissions to the minimum necessary for blog management.

Troubleshooting

If the client cannot recognize Halo MCP tools, verify that the HALO_BASE_URL is reachable and that HALO_TOKEN is valid. Check client configuration paths, restart the MCP client after changes, and review logs for authentication or network errors.

Examples and workflow notes

A typical flow starts with drafting content using the AI prompts, then using MCP tools to publish or organize posts. You can chain actions like create_post, update_post, publish_post, and list_categories to complete a full publishing pipeline through natural language.

Additional notes

Halo MCP Server supports a broad set of content-management capabilities, including posts, categories, tags, and attachments, all operable via natural language through MCP clients. You work with the server by providing intents and letting the system handle the exact tool calls and prompts behind the scenes.

Available tools

list_my_posts

List all your articles with pagination and filters.

get_post

Retrieve full details for a single post.

create_post

Create a new article with title, content, and metadata.

update_post

Update an existing article's title, content, or settings.

publish_post

Publish an article to make it visible on the site.

unpublish_post

Hide an article from public view without deleting it.

delete_post

Move an article to the recycle bin or permanently delete it.

get_post_draft

Fetch the content of a draft post.

update_post_draft

Modify the content of a draft post.

list_categories

List all categories with details.

get_category

Get details for a specific category.

create_category

Create a new category with optional parent, description, and cover.

update_category

Update a category's name, description, or cover.

delete_category

Remove a category.

get_category_posts

List posts under a specific category.

list_tags

List all tags with details.

get_tag

Get details for a specific tag.

create_tag

Create a new tag with optional color.

update_tag

Update a tag's name or color.

delete_tag

Delete a tag.

get_tag_posts

List posts associated with a tag.

list_console_tags

Show tags as shown in the console UI.

list_attachments

List uploaded attachments with filters.

get_attachment

Get details for a specific attachment.

upload_attachment

Upload a local file as an attachment.

upload_attachment_from_url

Upload an attachment directly from a URL.

delete_attachment

Delete an attachment.

list_attachment_groups

List attachment groups.

create_attachment_group

Create a new attachment group.

get_attachment_policies

View storage and retention policies for attachments.