# 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:
```bash
git clone https://github.com/nikolausm/huggingface-mcp-server.git
cd huggingface-mcp-server
```

2. Install dependencies:
```bash
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:
```bash
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):

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

## Usage

### Generate an Image

```javascript
// 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

```javascript
list_models()
```

### Check API Status

```javascript
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