nikolausm/huggingface-mcp-server

Hugging Face MCP Server

An MCP (Model Context Protocol) server that provides access to Hugging Face's AI image generation models, including Stable Diffusion.

Features

• Generate images using multiple Stable Diffusion models
• Support for negative prompts and guidance scale
• Save images locally or return as base64
• Check API status and token validity
• Free tier available (with rate limits)

Available Models

• Stable Diffusion 2.1: High-quality general purpose model
• Stable Diffusion XL: Latest and most advanced model
• OpenJourney: Midjourney-style artistic images
• Dreamlike Diffusion: Fantasy and artistic styles
• Anything v5: Anime/manga style images

Installation

1. Clone this repository:

git clone https://github.com/nikolausm/huggingface-mcp-server.git
cd huggingface-mcp-server

2. Install dependencies:

npm install

3. Get your Hugging Face API token:

   • Go to https://huggingface.co/settings/tokens
   • Create a new token (free)
   • Copy the token

4. Set up environment variable:

export HUGGINGFACE_TOKEN="your_token_here"

Configuration in Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "huggingface": {
      "command": "node",
      "args": ["/path/to/huggingface-mcp-server/index.js"],
      "env": {
        "HUGGINGFACE_TOKEN": "your_token_here"
      }
    }
  }
}

Usage

Generate an Image

// Basic usage
generate_image({
  prompt: "a cute guinea pig in a garden, children's book illustration style"
})

// Advanced usage
generate_image({
  prompt: "a beautiful landscape with mountains",
  model: "stable-diffusion-xl",
  negative_prompt: "ugly, blurry, low quality",
  guidance_scale: 10,
  save_path: "/tmp/landscape.png"
})

List Available Models

list_models()

Check API Status

check_status()

Free Tier Limitations

• Rate limited to ~10-20 requests per minute
• Some models may have queue times
• For production use, consider upgrading to a paid plan

Tips for Better Results

1. Be specific: "watercolor painting of a red barn" works better than just "barn"
2. Add style: Include art styles like "oil painting", "pencil sketch", "digital art"
3. Use negative prompts: Tell the model what to avoid
4. Adjust guidance scale: Higher values (10-15) follow prompts more closely

Examples

Children's Book Illustration

prompt: "cute guinea pig eating carrots, children's book illustration, watercolor style, soft colors"
negative_prompt: "realistic, photo, dark, scary"

Educational Diagram

prompt: "simple diagram of guinea pig anatomy, educational poster, labeled parts, clean design"
model: "stable-diffusion-xl"

License

MIT

Author

Michael Nikolaus