Halo MCP Server

🚀 Halo MCP Server

Integrate the Halo blogging system with AI assistants (such as Claude, Cursor, Qoder, Trae, etc.) seamlessly via MCP, making AI your blog management assistant.

🚀 Quick Start

📋 Prerequisites

1. Python 3.10 or higher

   python --version  # Make sure the version is >= 3.10
   

2. A running Halo blog system

   • Halo 2.21 or higher
   • Record the server address (e.g., http://localhost:8091 or https://yourdomain.com)

3. Claude Desktop or other MCP-compatible clients

   • Download link: Claude Desktop

📦 Installation

Method 1: Install from source code (for development)

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

# 2. Create a virtual environment (recommended)
python -m venv venv

# 3. Activate the virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# 4. Install the project (editable mode)
pip install -e .

Method 2: Install using pip (recommended)

pip install halo-mcp-server

🔧 Configuration

Step 1: Get the Halo access token

1. Log in to the Halo backend management system.
2. Go to Personal Center → Personal Tokens.
3. Click Generate New Token.
4. Set the token name (e.g., "MCP Server").
5. Select permissions (it is recommended to check all content management permissions).
6. Save and copy the generated token (it will only be displayed once).

Step 2: Configure Claude Desktop

Find and edit the Claude Desktop configuration file:

File location:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Configuration content:

{
  "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"
      }
    }
  }
}

📝 Configuration description:

💡 Tips:

1. When using a virtual environment, point command to the Python in the virtual environment:

   "command": "D:\\Project\\halo-mcp\\venv\\Scripts\\python.exe"
   

2. Find the Python path:

   # Windows
   where python
   
   # macOS/Linux
   which python
   

3. For remote Halo services, make sure to use the full URL (including http:// or https://).

Step 3: Restart Claude Desktop

Completely close and restart Claude Desktop to load the new configuration.

✅ Verify the installation

Enter the following test command in Claude Desktop:

Please list all my blog posts

Expected results:

• Claude will call the Halo MCP Server.
• Return your list of articles.
• If there are no articles, it will prompt "No articles yet".

Success indicators:

• ✅ No errors.
• ✅ Returned a list of articles or a prompt message.
• ✅ Claude understood the instruction "List articles".

✨ Features

📝 Article Management (9 tools)

🏷️ Category and Tag Management (13 tools)

📎 Attachment Management (8 tools)

• ✅ List attachments (supports filtering)
• ✅ Upload a local file
• ✅ Upload from a URL
• ✅ Delete an attachment
• ✅ Attachment group management
• ✅ View attachment details
• ✅ Create an attachment group
• ✅ View storage policies

🤖 AI Writing Assistant (10 Prompts)

💻 Usage Examples

📖 Complete example documentation: Check examples/README.md for 6 detailed examples and complete code.

🚀 Quick start: quick_start_example.md - Get to know the basic usage in 5 minutes.

🌟 Natural Language Interaction (Recommended)

The greatest advantage of the Halo MCP Server is that it supports natural language dialogue, eliminating the need to memorize complex commands:

📝 Article Creation

👤 User: Write and publish a technical article about Python asynchronous programming for me.

🤖 Claude:
Sure! I'll help you create this article.

[Automatically trigger the halo_blog_writing_assistant Prompt]
→ Generate a 2000-word professional article
→ Recommended tags: Python, asynchronous programming, asyncio
→ Recommended category: Technical tutorials
→ Call create_post to create the article
→ Call publish_post to publish the article

✓ The article "A Complete Guide to Python Asynchronous Programming" has been successfully created and published!

🔍 Article Management

# View articles
Please show me the 5 most recently published articles.

# Search for articles
Search for articles whose titles contain "Python".

# Edit an article
Change the title of the article "Python Tutorial" to "Python Getting Started Guide".

# Delete an article
Delete the article named "test-post".

✨ Content Optimization

# Optimize an article
Please optimize the article "Python Tutorial" to make it more accessible.

# Generate titles
Generate 5 attractive titles for this article.

# SEO optimization
Help optimize the SEO of this article with the keywords: Python, tutorial, getting started.

🏷️ Category and Tag Management

# Create a category
Create a category named "Technical Tutorials" with the description "Articles on various technical tutorials".

# Create tags
Create tags: Python, JavaScript, TypeScript, and set the color to blue.

# Batch operations
Add tags: Python, programming, tutorial to the article "Python Tutorial".

📎 Attachment Management

# Upload an image
Upload this image as the article cover: https://example.com/image.jpg.

# View attachments
List all image attachments.

# Create a group
Create an attachment group named "Article illustrations".

📚 Complete Workflow Example

Scenario: Publish a technical blog from scratch

👤 User: I want to write a technical article about Docker containerization.

🤖 Claude:
Sure! I'll help you complete the entire creation and publishing process.

Step 1: Content creation
[Trigger halo_blog_writing_assistant]
→ Generate a complete article (including an introduction, core concepts, practical examples, and a summary)

Step 2: Title optimization
[Trigger halo_title_generator]
→ Provide 5 title options for selection

Step 3: SEO optimization
[Trigger halo_seo_optimizer]
→ Optimize keyword layout
→ Generate a Meta description

Step 4: Category and tag management
[Trigger halo_tag_suggester]
→ Recommended tags: Docker, containerization, DevOps, cloud-native
[Trigger halo_category_suggester]
→ Recommended category: Cloud-native technology

Step 5: Create and publish
[Call create_post]
→ Create the article
[Call publish_post]
→ Publish the article

✓ Done! The article "A Practical Guide to Docker Containerization" has been successfully published.
  - Word count: 2000
  - Tags: Docker, containerization, DevOps, cloud-native
  - Category: Cloud-native technology
  - Article link: https://yourblog.com/posts/docker-guide

🎯 Core Concepts

MCP Tools vs Prompts

The Halo MCP Server provides two different capabilities:

💡 Actual workflow:

User: "Help me write a Python tutorial and publish it."
     ↓
Prompts: halo_blog_writing_assistant → Generate article content
     ↓
Tools: create_post → Create the article in Halo
     ↓
Tools: publish_post → Publish the article
     ↓
Result: ✓ The article has been created and published successfully.

Why can't you see the Prompts?

This is an excellent design of MCP:

• ✅ User-friendly - No need to memorize Prompt names.
• ✅ Intelligent matching - AI automatically understands intent and selects the appropriate Prompt.
• ✅ Seamless experience - Works automatically in the background, and users only need to describe their needs.
• ✅ Flexibility - Can express the same requirement in various ways.

Comparison with traditional methods:

# ❌ Traditional CLI method
$ halo-cli create-post \
  --title "Python Tutorial" \
  --content-file article.md \
  --tags "Python,tutorial" \
  --category "Programming" \
  --publish

# ✅ MCP method (natural language)
Help me write a Python tutorial and publish it.

📚 Documentation

Core Documentation

API Documentation

📖 Example Code

💡 Complete example guide: Check examples/README.md for detailed example documentation and usage instructions.

📁 Example Directory Structure

examples/
├── README.md                           # 📘 Overview and detailed guide for examples
├── quick_start_example.md              # ⚡ Quick start (must-read)
├── usage_examples.md                   # 📚 Collection of usage examples
├── category_management_examples.py     # 🏷️ Complete example of category management
├── tag_management_examples.py          # 🔖 Complete example of tag management
├── attachment_management_examples.py   # 📎 Complete example of attachment management
└── mcp_prompts_examples.py             # 🤖 Example of AI writing assistant

🚀 Quick Start

Recommended path for beginners:

1. 📖 Quick Start Example - Get to know the basic usage in 5 minutes.
2. 📚 Collection of Usage Examples - Common scenarios and best practices.
3. 📘 Complete Example Guide - Detailed documentation for all examples.

Learn by function:

💡 Usage Tips

• Markdown examples (.md) - Suitable for reading and understanding, containing detailed explanations.
• Python examples (.py) - Complete code that can be run directly, containing comments.
• From simple to complex - It is recommended to learn in the order shown in the table above to gradually master all functions.

Run Python examples:

# 1. Make sure the environment variables are configured
export HALO_BASE_URL="your_url"
export HALO_TOKEN="your_token"

# 2. Run an example (taking category management as an example)
cd examples
python category_management_examples.py

🔧 Configuration Instructions

Environment Variables

Create a .env file or set the following in the Claude Desktop configuration:

# ========== Required Configuration ==========
HALO_BASE_URL=http://localhost:8091    # Halo server address
HALO_TOKEN=your_token_here              # API access token

# ========== Optional Configuration ==========
MCP_LOG_LEVEL=INFO                      # Log level: DEBUG, INFO, WARNING, ERROR
MCP_TIMEOUT=30                          # HTTP request timeout (seconds)

# ========== Feature Switches ==========
ENABLE_IMAGE_COMPRESSION=true           # Enable image compression
IMAGE_MAX_WIDTH=1920                    # Maximum width after compression (pixels)
IMAGE_QUALITY=85                        # Image quality (1-100)
MAX_UPLOAD_SIZE_MB=10                   # Maximum upload size (MB)

# ========== Advanced Configuration ==========
HTTP_POOL_SIZE=10                       # HTTP connection pool size
MAX_RETRIES=3                           # Number of request retries
ENABLE_CACHE=true                       # Enable caching
CACHE_TTL=300                           # Cache expiration time (seconds)

Refer to .env.example for a complete configuration description.

🛠️ Troubleshooting

Common Issues

1. Claude cannot recognize Halo tools

Symptom: Claude does not respond to blog management commands.

Solution:

# Check the configuration file
# Windows: %APPDATA%\Claude\claude_desktop_config.json
# macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

# Verify the configuration format (JSON must be correct)
# Make sure the Python path is correct
# Restart Claude Desktop

2. Authentication failure

Symptom: Error messages such as "Authentication failed" or "Invalid token".

Solution:

1. Check if HALO_TOKEN is correct (no extra spaces).
2. Make sure the token has not expired.
3. Verify that HALO_BASE_URL is accessible.
4. Test the network connection:

   curl http://localhost:8091/apis/api.console.halo.run/v1alpha1/posts
   

3. Module import error

Symptom: "No module named 'halo-mcp-server'".

Solution:

# Reinstall the module
pip install -e .

# Verify the installation
pip show halo-mcp-server

# Check the Python path
python -c "import halo-mcp-server; print(halo_mcp_server.__version__)"

4. Prompts do not work

Symptom: AI cannot automatically generate article content.

Explanation: Prompts are hidden and triggered by natural language.

Test method:

# ✅ Correct way (will trigger the writing Prompt)
Help me write an article about Python.

# ❌ Incorrect understanding (not necessary)
Use halo_blog_writing_assistant to write an article.

Debugging Methods

View Logs

Set the debug level:

{
  "mcpServers": {
    "halo": {
      "env": {
        "MCP_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Log locations:

• Claude Desktop logs: Help → Developer Tools → Console
• MCP service logs: Check the standard output

Manual Testing

Test authentication:

# Use curl to test
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8091/apis/uc.api.content.halo.run/v1alpha1/posts

Test the Python module:

# Enter the Python environment
python

# Import and test
>>> from halo_mcp_server.client import HaloClient
>>> import asyncio
>>> client = HaloClient()
>>> asyncio.run(client.authenticate())
>>> print("✓ Authentication successful")

🏗️ Development

Development Environment Setup

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

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

# 3. Install development dependencies
pip install -e ".[dev]"

# 4. Install pre-commit hooks
pre-commit install

Project Structure

halo-mcp-server/
├── src/halo-mcp-server/           # Source code
│   ├── __init__.py
│   ├── __main__.py         # Entry file
│   ├── config.py           # Configuration management
│   ├── server.py           # MCP server
│   ├── exceptions.py       # Exception definitions
│   ├── client/             # Halo API client
│   │   ├── base.py
│   │   └── halo_client.py
│   ├── tools/              # MCP Tools
│   │   ├── post_tools.py
│   │   ├── category_tools.py
│   │   ├── tag_tools.py
│   │   └── attachment_tools.py
│   ├── prompts/            # MCP Prompts
│   │   └── blog_prompts.py
│   └── utils/              # Utility functions
│       └── logger.py
├── tests/                  # Unit tests
├── examples/               # Usage examples
├── halo_apis_docs/         # API documentation
├── debug_tests/            # Debugging scripts
├── pyproject.toml          # Project configuration
└── README.md               # This file

Code Style

# Format the code
black src/ tests/
isort src/ tests/

# Type checking
mypy src/

# Code linting
ruff check src/ tests/

# Run tests
pytest tests/ -v --cov=halo-mcp-server

Add New Features

1. Add a new Tool:

   # src/halo-mcp-server/tools/custom_tools.py
   from mcp.types import Tool
   
   async def my_custom_tool(client, arguments):
       """Implement your tool logic"""
       pass
   
   MY_TOOLS = [
       Tool(
           name="my_tool",
           description="Tool description",
           inputSchema={...}
       )
   ]
   

2. Add a new Prompt:

   # src/halo-mcp-server/prompts/custom_prompts.py
   from mcp.types import Prompt, PromptArgument
   
   CUSTOM_PROMPTS = [
       Prompt(
           name="my_prompt",
           description="Prompt description",
           arguments=[...]
       )
   ]
   

3. Register with the Server:

   # src/halo-mcp-server/server.py
   from halo_mcp_server.tools.custom_tools import MY_TOOLS
   from halo_mcp_server.prompts.custom_prompts import CUSTOM_PROMPTS
   
   # Add to the corresponding lists
   all_tools += MY_TOOLS
   all_prompts += CUSTOM_PROMPTS
   

Contribution Guidelines

Contributions are welcome! Please check DEVELOPMENT.md for detailed information.

🧪 Testing

Quick Testing

The project provides a comprehensive test suite covering all 30 MCP tools:

# Enter the test directory
cd tests

# Run the comprehensive test
python run_comprehensive_test.py

Test Coverage

✅ Category Management (6 tools): create_category, list_categories, get_category, update_category, get_category_posts, delete_category

✅ Tag Management (7 tools): create_tag, list_tags, get_tag, update_tag, list_console_tags, get_tag_posts, delete_tag

✅ Attachment Management (8 tools): Upload, list, delete, group management, etc.

✅ Article Management (9 tools): Create, edit, publish, draft management, etc.

Test Details

Check tests/README.md for:

• 📝 Detailed test guide
• 🔧 Environment configuration instructions
• 🐛 Troubleshooting methods
• 📊 Test report generation

📊 Feature Comparison Table

Complete Tool List (30 tools)

Complete Prompts List (10 Prompts)

🤝 Contribution

Contributions of code, issue reports, or suggestions are welcome!

Ways to Contribute

1. Fork the project.
2. Create a feature branch (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'Add some AmazingFeature').
4. Push to the branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

Contributors

Thank you to all developers who have contributed to the project!

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Halo - An excellent open-source blog system.
• Model Context Protocol - A powerful AI integration protocol.
• Claude - An intelligent AI assistant.
• All contributors and users.

📞 Contact Us

• Project homepage: GitHub
• Issue feedback: Issues
• Documentation: Documentation

🎁 Support the Project

If this project is helpful to you, you can support it in the following ways:

• ⭐ Give the project a Star.
• 🐛 Submit an Issue or PR.
• 💬 Share it with more people.
• ☕ Make a donation to the author.