AI Picture MCP Server

![NPM Version](https://www.npmjs.com/package/aipic-mcp)
![License: MIT](https://opensource.org/licenses/MIT)
![GitHub Stars](https://github.com/leonaries/aipic-mcp/stargazers)
![TypeScript](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 viaDASHSCOPE_API_KEY or MODELSCOPE_API_KEY

`📦 Installation & Usage`

`$3`

Use directly with NPX without installation:

`bash npx -y aipic-mcp`

Claude Desktop Configuration:`json { "mcpServers": { "aipic": { "command": "npx", "args": ["-y", "aipic-mcp"] } } }`

`$3`

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" } } } }`

`$3`

`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" } } } }`

`$3`

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`

`$3`

Add the server to your Claude Desktop configuration file:

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

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

`$3`

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:

`$3`

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

`$3`

`bash npm run dev`

`$3`

`bash npm run build`

`$3`

`bash npm test`

`$3`

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`

`$3`

1. "Command not found" error - Make sure you have Node.js 18+ installed - Try runningnpx -y aipic-mcpinstead 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 withsk-) - Check that you have sufficient quota on your Alibaba Cloud account - Ensure the API key is correctly configured asDASHSCOPE_API_KEYenvironment 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-yflag 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`

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

$3

- 🔧 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

$3

- 🎉 Initial release with ModelScope integration

---

🌟 Star this repository if you find it useful!

AI Picture MCP Server

🚀 Quick Start

``bash npx -y aipic-mcp`

`✨ Features`

`📦 Installation & Usage`

`$3`

Use directly with NPX without installation:

`bash npx -y aipic-mcp`

Claude Desktop Configuration:`json { "mcpServers": { "aipic": { "command": "npx", "args": ["-y", "aipic-mcp"] } } }`

`$3`

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" } } } }`

`$3`

`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" } } } }`

`$3`

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`

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

`⚙️ Configuration`

`$3`

Add the server to your Claude Desktop configuration file:

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

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

`$3`

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

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:

`$3`

Generates an AI image optimized for web design use.

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

`🔧 API Integration Details`

`🛡️ Error Handling`

`🔨 Development`

`$3`

`bash npm run dev`

`$3`

`bash npm run build`

`$3`

`bash npm test`

`$3`

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.

`🔒 Security Considerations`

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

`$3`

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

5. NPX installation issues - Use the-yflag 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`

`📝 Changelog`

`$3`


- ⚡ Smart File Saving: Auto-saves images to Desktop when possible, falls back to temp directory
- 🔧 Enhanced Environment Variables: Primary support for

$3

- 🎉 Initial release with ModelScope integration

---

🌟 Star this repository if you find it useful!