AI Picture MCP Server

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

2. Install dependencies:

npm install

3. Build the TypeScript code:

npm run build

4. 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 LICENSE file for details.

🔗 Links

• NPM Package: https://www.npmjs.com/package/aipic-mcp
• GitHub Repository: https://github.com/leonaries/aipic-mcp
• Alibaba Cloud DashScope: https://dashscope.aliyun.com/
• Model Context Protocol: https://modelcontextprotocol.io/

📝 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!