aipic-mcp

leonaries/aipic-mcp

3.1

If you are the rightful owner of aipic-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

AI Picture MCP Server is a Model Context Protocol server designed to generate AI-powered images for web design workflows using ModelScope's FLUX model.

AI Picture MCP Server

NPM Version License: MIT GitHub Stars TypeScript

A Model Context Protocol (MCP) server that provides AI-powered image generation capabilities specifically designed for web design workflows. This server integrates with Alibaba Cloud DashScope's FLUX model to generate high-quality images based on English prompts, perfect for creating placeholder images, hero images, product mockups, and other web assets.

🚀 Quick Start

npx -y aipic-mcp

✨ Features

  • 🎨 AI Image Generation: Generate high-quality images using DashScope FLUX model with natural language prompts
  • 🖥️ Web-Optimized Output: Automatically optimizes images for web use with proper compression and sizing
  • 📏 Flexible Sizing: Support for custom width and height specifications (default: 1024x1024)
  • 📋 Base64 Encoding: Returns images in base64 format for direct use in web applications
  • ⚡ Smart File Saving: Auto-saves to Desktop when possible, falls back to temp directory
  • 🔄 Async Processing: Uses DashScope's async task API for reliable image generation
  • 🛡️ Robust Error Handling: Comprehensive error handling for API issues, network problems, and invalid inputs
  • 🔐 Environment Variable Support: Configure API keys via DASHSCOPE_API_KEY or MODELSCOPE_API_KEY

📦 Installation & Usage

Option 1: NPX (Recommended)

Use directly with NPX without installation:

npx -y aipic-mcp

Claude Desktop Configuration:

{
  "mcpServers": {
    "aipic": {
      "command": "npx",
      "args": ["-y", "aipic-mcp"]
    }
  }
}

Option 2: NPX with API Key Environment Variable (Recommended)

For the best experience, configure your DashScope API key as an environment variable:

{
  "mcpServers": {
    "aipic": {
      "command": "npx",
      "args": ["-y", "aipic-mcp"],
      "env": {
        "DASHSCOPE_API_KEY": "sk-your-dashscope-api-key-here"
      }
    }
  }
}

With full PATH (if using NVM or custom Node installation):

{
  "mcpServers": {
    "aipic": {
      "command": "/Users/your-username/.nvm/versions/node/v20.19.4/bin/npx",
      "args": ["-y", "aipic-mcp"],
      "env": {
        "DASHSCOPE_API_KEY": "sk-your-dashscope-api-key-here",
        "PATH": "/Users/your-username/.nvm/versions/node/v20.19.4/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Option 3: Global Installation

npm install -g aipic-mcp

Claude Desktop Configuration:

{
  "mcpServers": {
    "aipic": {
      "command": "aipic-mcp"
    }
  }
}

With API Key Environment Variable:

{
  "mcpServers": {
    "aipic": {
      "command": "aipic-mcp",
      "env": {
        "DASHSCOPE_API_KEY": "sk-your-dashscope-api-key-here"
      }
    }
  }
}

Option 4: Local Development

If you want to contribute to the project or customize it:

  1. Clone this repository:
git clone https://github.com/leonaries/aipic-mcp.git
cd aipic-mcp
  1. Install dependencies:
npm install
  1. Build the TypeScript code:
npm run build
  1. Test locally:
npm run dev

Claude Desktop Configuration for Local Development:

{
  "mcpServers": {
    "aipic": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/Users/your-username/path/to/aipic-mcp",
      "env": {
        "DASHSCOPE_API_KEY": "sk-your-dashscope-api-key-here"
      }
    }
  }
}

Note: Replace /Users/your-username/path/to/aipic-mcp with the actual path where you cloned the repository.

⚙️ Configuration

Claude Desktop Setup

Add the server to your Claude Desktop configuration file:

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

Choose one of the configuration options above based on your installation method.

DashScope API Key

You'll need a DashScope API key from Alibaba Cloud to use this server. Get one from Alibaba Cloud DashScope.

How to get your API key:

  1. Visit Alibaba Cloud DashScope
  2. Sign up/login to your account
  3. Go to API Keys section
  4. Create a new API key with image generation permissions
  5. Copy the API key (format: sk-xxxxxxxxxx)

Two ways to provide your API key:

  1. Environment Variable (Recommended): Configure in Claude Desktop config as shown above
  2. Runtime Parameter: Pass the API key when calling the tool (less convenient but more flexible)

🎯 Usage

The server provides one main tool:

generate_web_image

Generates an AI image optimized for web design use.

Parameters:

  • prompt (required): English description of the image to generate
  • apiKey (optional): Your DashScope API key (if not set via DASHSCOPE_API_KEY environment variable)
  • width (optional): Image width in pixels (default: 1024)
  • height (optional): Image height in pixels (default: 1024)
  • outputPath (optional): Custom path to save the image (default: auto-saves to Desktop or temp directory)

Example prompts:

  • "A modern minimalist office workspace with laptop and coffee cup"
  • "Abstract geometric background in blue and purple gradients"
  • "Professional team meeting in a bright conference room"
  • "E-commerce product photo of wireless headphones on white background"
  • "Hero image of a mountain landscape at sunrise"

Example usage in Claude (with environment variable configured):

Generate a hero image for my website with the prompt "A sleek modern smartphone floating above a city skyline at dusk"

Example usage in Claude (with manual API key):

Generate a hero image for my website with the prompt "A sleek modern smartphone floating above a city skyline at dusk" using my DashScope API key "sk-your-api-key-here"

🔧 API Integration Details

This server uses the Alibaba Cloud DashScope API with the following configuration:

  • Model: flux-schnell (FLUX.1 schnell model for fast generation)
  • Endpoint: https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
  • Authentication: Bearer token (your DashScope API key)
  • Mode: Async processing with task polling
  • Timeout: 5 minutes for generation, 30 seconds for download

🛡️ Error Handling

The server handles various error conditions:

  • Invalid or missing API keys
  • Rate limiting from DashScope API
  • Network timeouts and connectivity issues
  • Task generation failures
  • Image download failures
  • File system errors when saving images

🔨 Development

Running in Development Mode

npm run dev

Building for Production

npm run build

Testing

npm test

Publishing to NPM

The project is already published to NPM. For maintainers:

npm run build
npm version patch  # or minor/major
npm publish

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

  1. Fork the repository
  2. Create your 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

🔒 Security Considerations

  • API keys can be configured via environment variables for better security
  • Images are saved to the local filesystem under the current working directory
  • Network requests have appropriate timeouts to prevent hanging
  • Input validation prevents empty prompts and missing required parameters
  • Environment variables are more secure than hardcoded keys

📚 Dependencies

  • @modelcontextprotocol/sdk: MCP SDK for server implementation
  • axios: HTTP client for API requests
  • sharp: Image processing and optimization
  • uuid: Unique ID generation for filenames

🐛 Troubleshooting

Common Issues

  1. "Command not found" error

    • Make sure you have Node.js 18+ installed
    • Try running npx -y aipic-mcp instead of global installation
    • If using NVM, specify the full path to npx in your configuration

  2. API key errors

    • Verify your DashScope API key is valid (should start with sk-)
    • Check that you have sufficient quota on your Alibaba Cloud account
    • Ensure the API key is correctly configured as DASHSCOPE_API_KEY environment variable
    • Make sure your API key has image generation permissions

  3. Image generation timeout

    • DashScope API can take up to 2-3 minutes for complex prompts
    • Try again with a simpler prompt
    • Check your internet connection

  4. Environment variable not working

    • Restart Claude Desktop after updating the configuration
    • Verify the JSON syntax in your configuration file
    • Check that the API key doesn't have extra spaces or quotes

  5. NPX installation issues

    • Use the -y flag to automatically confirm installations
    • If using NVM, make sure your PATH is correctly set in the configuration

  6. Task generation failures

    • The server uses async processing, so it may take a few moments
    • Check the console logs for detailed error messages
    • Ensure your prompt is in English for best results

📄 License

MIT License - see file for details.

🔗 Links

📝 Changelog

v1.0.4 (Latest)

  • 📝 Documentation Update: Comprehensive README improvements with enhanced feature descriptions
  • 🔧 API Key Format: Updated all examples to use correct sk- prefix for DashScope API keys
  • 🌐 Environment Variables: Clarified primary use of DASHSCOPE_API_KEY over legacy MODELSCOPE_API_KEY
  • ✨ User Experience: Improved installation guides and troubleshooting documentation

v1.0.3

  • ⚡ Smart File Saving: Auto-saves images to Desktop when possible, falls back to temp directory
  • 🔧 Enhanced Environment Variables: Primary support for DASHSCOPE_API_KEY, backward compatible with MODELSCOPE_API_KEY
  • 🛡️ Improved Error Handling: Better error messages and more robust API integration
  • 📁 Intelligent Path Detection: Automatic directory creation and fallback mechanisms
  • 🚀 Better User Experience: Images now saved directly to user's Desktop by default

v1.0.1

  • 🔧 BREAKING CHANGE: Updated to use Alibaba Cloud DashScope API instead of ModelScope API
  • ✨ Added async task processing for more reliable image generation
  • 🐛 Fixed API authentication issues
  • 📚 Updated documentation to reflect DashScope integration

v1.0.0

  • 🎉 Initial release with ModelScope integration

🌟 Star this repository if you find it useful!