# AI Picture MCP Server
[](https://www.npmjs.com/package/aipic-mcp)
[](https://opensource.org/licenses/MIT)
[](https://github.com/leonaries/aipic-mcp/stargazers)
[](https://www.typescriptlang.org/)
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
```bash
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:
```bash
npx -y aipic-mcp
```
**Claude Desktop Configuration:**
```json
{
"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:
```json
{
"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):**
```json
{
"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
```bash
npm install -g aipic-mcp
```
**Claude Desktop Configuration:**
```json
{
"mcpServers": {
"aipic": {
"command": "aipic-mcp"
}
}
}
```
**With API Key Environment Variable:**
```json
{
"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:
```bash
git clone https://github.com/leonaries/aipic-mcp.git
cd aipic-mcp
```
2. Install dependencies:
```bash
npm install
```
3. Build the TypeScript code:
```bash
npm run build
```
4. Test locally:
```bash
npm run dev
```
**Claude Desktop Configuration for Local Development:**
```json
{
"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](https://dashscope.aliyun.com/).
**How to get your API key:**
1. Visit [Alibaba Cloud DashScope](https://dashscope.aliyun.com/)
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
```bash
npm run dev
```
### Building for Production
```bash
npm run build
```
### Testing
```bash
npm test
```
### Publishing to NPM
The project is already published to NPM. For maintainers:
```bash
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](./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!**
