siliconflow-image-mcp 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +306 -0
- package/bin/siliconflow-image-mcp +24 -0
- package/bin/siliconflow-image-mcp.cmd +21 -0
- package/dist/LICENSE +21 -0
- package/dist/README.md +306 -0
- package/dist/index.js +605 -0
- package/dist/index.js.map +7 -0
- package/dist/package.json +33 -0
- package/package.json +70 -0
- package/src/index.ts +149 -0
- package/src/services/siliconflow.ts +320 -0
- package/src/tools/edit.test.ts +147 -0
- package/src/tools/edit.ts +71 -0
- package/src/tools/generate.test.ts +163 -0
- package/src/tools/generate.ts +93 -0
- package/src/tools/list-models.test.ts +116 -0
- package/src/tools/list-models.ts +82 -0
- package/src/types/index.ts +115 -0
- package/src/utils/file.ts +54 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 SiliconFlow Image MCP Contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,306 @@
|
|
|
1
|
+
# SiliconFlow Image MCP
|
|
2
|
+
|
|
3
|
+
A Model Context Protocol (MCP) server for image generation and editing using **SiliconFlow** - optimized for China users with fast, reliable access.
|
|
4
|
+
|
|
5
|
+
## โจ Features
|
|
6
|
+
|
|
7
|
+
- ๐จ๐ณ **China Optimized** - Fast, reliable access from mainland China without VPN
|
|
8
|
+
- ๐ผ๏ธ **Image Generation** - Generate stunning images from text prompts
|
|
9
|
+
- โ๏ธ **Image Editing** - Edit existing images with AI-powered modifications
|
|
10
|
+
- ๐ **Model Discovery** - Browse available image generation models
|
|
11
|
+
- ๐ **Multiple Formats** - Support for various aspect ratios and resolutions
|
|
12
|
+
- ๐ **Easy Integration** - Simple setup with Claude Desktop and other MCP clients
|
|
13
|
+
- โก **Advanced Options** - Negative prompts, seeds, CFG values
|
|
14
|
+
- ๐ฅ๏ธ **Cross-Platform** - Native support for Linux, macOS, and Windows
|
|
15
|
+
- ๐ **Custom Storage** - Configure where images are saved via environment variable
|
|
16
|
+
- ๐งช **Mock Mode** - Test without making real API calls
|
|
17
|
+
|
|
18
|
+
## ๐ฆ Installation
|
|
19
|
+
|
|
20
|
+
### Using NPX (Recommended)
|
|
21
|
+
```bash
|
|
22
|
+
# No installation needed - use directly via npx
|
|
23
|
+
npx siliconflow-image-mcp
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
### Global Install
|
|
27
|
+
```bash
|
|
28
|
+
npm install -g siliconflow-image-mcp
|
|
29
|
+
siliconflow-image-mcp
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## โ๏ธ Setup
|
|
33
|
+
|
|
34
|
+
### 1. Get SiliconFlow API Key
|
|
35
|
+
- Visit [SiliconFlow Console](https://siliconflow.cn)
|
|
36
|
+
- Create an account and get your API key
|
|
37
|
+
- The service is optimized for China network conditions
|
|
38
|
+
|
|
39
|
+
### 2. Configure Environment
|
|
40
|
+
```bash
|
|
41
|
+
export SILICONFLOW_API_KEY="your-siliconflow-api-key"
|
|
42
|
+
|
|
43
|
+
# Optional: Custom directory for saved images (default: system temp dir)
|
|
44
|
+
export SILICONFLOW_IMAGE_DIR="/path/to/your/images"
|
|
45
|
+
|
|
46
|
+
# Optional: Mock mode for testing (no real API calls)
|
|
47
|
+
export SILICONFLOW_MOCK="true"
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### 3. Claude Desktop Configuration
|
|
51
|
+
|
|
52
|
+
Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{
|
|
56
|
+
"mcpServers": {
|
|
57
|
+
"siliconflow-image-mcp": {
|
|
58
|
+
"command": "npx",
|
|
59
|
+
"args": ["-y", "siliconflow-image-mcp"],
|
|
60
|
+
"env": {
|
|
61
|
+
"SILICONFLOW_API_KEY": "your-siliconflow-key",
|
|
62
|
+
"SILICONFLOW_IMAGE_DIR": "/path/to/save/images"
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
**Restart Claude Desktop** after adding the configuration.
|
|
70
|
+
|
|
71
|
+
## ๐ ๏ธ Available Tools
|
|
72
|
+
|
|
73
|
+
### 1. `generate_image`
|
|
74
|
+
Generate images from text descriptions.
|
|
75
|
+
|
|
76
|
+
**Parameters:**
|
|
77
|
+
- `prompt` (required): Detailed description of the image to generate
|
|
78
|
+
- `model` (optional): Model ID (default: `black-forest-labs/FLUX.1-dev`)
|
|
79
|
+
- `aspectRatio` (optional): Aspect ratio - `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`
|
|
80
|
+
- `imageSize` (optional): Image size - `1K`, `2K`, `4K`
|
|
81
|
+
- `count` (optional): Number of images (1-4, default: 1)
|
|
82
|
+
- `negativePrompt` (optional): What to avoid in the image
|
|
83
|
+
- `seed` (optional): Seed for reproducible results
|
|
84
|
+
|
|
85
|
+
**Example:**
|
|
86
|
+
```
|
|
87
|
+
Generate a beautiful sunset over mountains with a lake in the foreground,
|
|
88
|
+
in 16:9 aspect ratio, 4K resolution
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### 2. `edit_image`
|
|
92
|
+
Edit existing images with AI instructions.
|
|
93
|
+
|
|
94
|
+
**Parameters:**
|
|
95
|
+
- `image` (required): Base64 encoded image data or image URL
|
|
96
|
+
- `prompt` (required): Instructions for editing
|
|
97
|
+
- `model` (optional): Model ID (default: `Qwen/Qwen-Image-Edit-2509`)
|
|
98
|
+
|
|
99
|
+
**Example:**
|
|
100
|
+
```
|
|
101
|
+
Edit this image to make it brighter and increase the saturation
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
### 3. `list_image_models`
|
|
105
|
+
List all available image generation models.
|
|
106
|
+
|
|
107
|
+
**Parameters:** None
|
|
108
|
+
|
|
109
|
+
**Example:**
|
|
110
|
+
```
|
|
111
|
+
Show me available image generation models
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## ๐ก Usage Examples
|
|
115
|
+
|
|
116
|
+
### Basic Image Generation
|
|
117
|
+
```
|
|
118
|
+
Generate an image of a futuristic cityscape at night with neon lights
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### Multiple Images
|
|
122
|
+
```
|
|
123
|
+
Generate 3 different variations of a cute cat wearing a hat
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### Specific Aspect Ratio
|
|
127
|
+
```
|
|
128
|
+
Create a portrait of a wizard in 9:16 aspect ratio for mobile wallpaper
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### High Resolution
|
|
132
|
+
```
|
|
133
|
+
Generate a detailed landscape in 4K resolution with 16:9 aspect ratio
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
### Image Editing
|
|
137
|
+
```
|
|
138
|
+
Edit this image to make it look like a vintage photograph from the 1950s
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
### Advanced Options
|
|
142
|
+
```
|
|
143
|
+
Generate a photorealistic portrait using black-forest-labs/FLUX.1-dev
|
|
144
|
+
with negative prompt "blurry, low quality" and seed 12345
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
## ๐ง Model Recommendations
|
|
148
|
+
|
|
149
|
+
### SiliconFlow Models
|
|
150
|
+
- `black-forest-labs/FLUX.1-dev` - High quality general purpose (default)
|
|
151
|
+
- `Qwen/Qwen-Image-Edit-2509` - Excellent for image editing (default)
|
|
152
|
+
- `Kwai-Kolors/Kolors` - Good for artistic styles
|
|
153
|
+
- `stabilityai/stable-diffusion-xl-base-1.0` - Classic stable diffusion
|
|
154
|
+
|
|
155
|
+
## ๐ China-Specific Benefits
|
|
156
|
+
|
|
157
|
+
### SiliconFlow Advantages:
|
|
158
|
+
- โ
**Fast access** from mainland China
|
|
159
|
+
- โ
**Stable connection** without VPN
|
|
160
|
+
- โ
**Chinese language support**
|
|
161
|
+
- โ
**Local payment methods**
|
|
162
|
+
- โ
**Optimized infrastructure**
|
|
163
|
+
|
|
164
|
+
### Network Performance:
|
|
165
|
+
- Average response time: < 2 seconds from China
|
|
166
|
+
- 99.9% uptime from Chinese networks
|
|
167
|
+
- No Great Firewall interference
|
|
168
|
+
|
|
169
|
+
## ๐ง Environment Variables
|
|
170
|
+
|
|
171
|
+
| Variable | Required | Default | Description |
|
|
172
|
+
|----------|----------|---------|-------------|
|
|
173
|
+
| `SILICONFLOW_API_KEY` | **Yes** | - | Your SiliconFlow API key from [siliconflow.cn](https://siliconflow.cn) |
|
|
174
|
+
| `SILICONFLOW_IMAGE_DIR` | No | System temp dir | Custom directory to save generated/edited images |
|
|
175
|
+
| `SILICONFLOW_MOCK` | No | `false` | Enable mock mode for testing (no real API calls) |
|
|
176
|
+
|
|
177
|
+
### Examples
|
|
178
|
+
|
|
179
|
+
**Linux/macOS:**
|
|
180
|
+
```bash
|
|
181
|
+
export SILICONFLOW_API_KEY="sk-xxxxx"
|
|
182
|
+
export SILICONFLOW_IMAGE_DIR="/home/user/siliconflow-images"
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
**Windows CMD:**
|
|
186
|
+
```cmd
|
|
187
|
+
set SILICONFLOW_API_KEY=sk-xxxxx
|
|
188
|
+
set SILICONFLOW_IMAGE_DIR=C:\Users\MyUser\Images
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
**Windows PowerShell:**
|
|
192
|
+
```powershell
|
|
193
|
+
$env:SILICONFLOW_API_KEY="sk-xxxxx"
|
|
194
|
+
$env:SILICONFLOW_IMAGE_DIR="C:\Users\MyUser\Images"
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
## ๐ Security
|
|
198
|
+
|
|
199
|
+
- **API Key**: Your API keys are stored securely in environment variables
|
|
200
|
+
- **Input Validation**: All inputs are validated using Zod schemas
|
|
201
|
+
- **Rate Limiting**: Respect service provider limits
|
|
202
|
+
- **Content Filtering**: Consider implementing content policies for your use case
|
|
203
|
+
- **File Storage**: Images are saved to your specified directory or system temp
|
|
204
|
+
|
|
205
|
+
## ๐ Troubleshooting
|
|
206
|
+
|
|
207
|
+
### "No API key provided"
|
|
208
|
+
Make sure you've set the environment variable:
|
|
209
|
+
```bash
|
|
210
|
+
export SILICONFLOW_API_KEY="your-key"
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
### "Failed to connect to SiliconFlow"
|
|
214
|
+
- Check your API key is valid
|
|
215
|
+
- Verify network connectivity to `api.siliconflow.cn`
|
|
216
|
+
- Check SiliconFlow service status
|
|
217
|
+
|
|
218
|
+
### "No images were generated"
|
|
219
|
+
- Try a more descriptive prompt
|
|
220
|
+
- Check if the model supports image generation
|
|
221
|
+
- Verify your API key has access to the model
|
|
222
|
+
|
|
223
|
+
### Images not appearing in Claude
|
|
224
|
+
- Restart Claude Desktop after configuration changes
|
|
225
|
+
- Check the MCP server logs for errors
|
|
226
|
+
- Verify the server is running with `npm start`
|
|
227
|
+
|
|
228
|
+
### Images saved to wrong location
|
|
229
|
+
- Set `SILICONFLOW_IMAGE_DIR` to your desired path
|
|
230
|
+
- Ensure the directory exists and is writable
|
|
231
|
+
- Default location: system temp directory (`/tmp/siliconflow-images/` on Linux/macOS)
|
|
232
|
+
|
|
233
|
+
### Running on Windows
|
|
234
|
+
- Use the `.cmd` wrapper automatically provided by npm
|
|
235
|
+
- Or use Git Bash/WSL for Unix-style commands
|
|
236
|
+
- For native CMD/PowerShell, the `.cmd` file handles execution
|
|
237
|
+
|
|
238
|
+
## ๐ฐ Pricing
|
|
239
|
+
|
|
240
|
+
### SiliconFlow:
|
|
241
|
+
- **FLUX.1-dev**: ~ยฅ0.02-0.05 per image
|
|
242
|
+
- **Qwen-Image**: ~ยฅ0.01-0.03 per image
|
|
243
|
+
- **Kolors**: ~ยฅ0.01-0.02 per image
|
|
244
|
+
- **Free tier**: Available for new users
|
|
245
|
+
|
|
246
|
+
*Check [SiliconFlow pricing](https://siliconflow.cn/pricing) for current rates.*
|
|
247
|
+
|
|
248
|
+
## ๐ Development
|
|
249
|
+
|
|
250
|
+
### Local Development
|
|
251
|
+
```bash
|
|
252
|
+
# Clone the repository
|
|
253
|
+
git clone https://github.com/martianzhang/siliconflow-image-mcp.git
|
|
254
|
+
cd siliconflow-image-mcp
|
|
255
|
+
|
|
256
|
+
# Install dependencies
|
|
257
|
+
npm install
|
|
258
|
+
|
|
259
|
+
# Build the project
|
|
260
|
+
npm run build
|
|
261
|
+
|
|
262
|
+
# Run tests
|
|
263
|
+
npm test
|
|
264
|
+
|
|
265
|
+
# Start the server
|
|
266
|
+
npm start
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
### Project Structure
|
|
270
|
+
```
|
|
271
|
+
src/
|
|
272
|
+
โโโ index.ts # Main server entry
|
|
273
|
+
โโโ tools/
|
|
274
|
+
โ โโโ generate.ts # Image generation tool
|
|
275
|
+
โ โโโ edit.ts # Image editing tool
|
|
276
|
+
โ โโโ list-models.ts # Model discovery tool
|
|
277
|
+
โโโ services/
|
|
278
|
+
โ โโโ siliconflow.ts # SiliconFlow service wrapper
|
|
279
|
+
โโโ types/
|
|
280
|
+
โโโ index.ts # Type definitions
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
## ๐ค Contributing
|
|
284
|
+
|
|
285
|
+
Contributions are welcome! Please feel free to submit a Pull Request.
|
|
286
|
+
|
|
287
|
+
1. Fork the repository
|
|
288
|
+
2. Create a feature branch
|
|
289
|
+
3. Make your changes
|
|
290
|
+
4. Add tests for new functionality
|
|
291
|
+
5. Submit a pull request
|
|
292
|
+
|
|
293
|
+
## ๐ License
|
|
294
|
+
|
|
295
|
+
MIT License - see [LICENSE](LICENSE) for details.
|
|
296
|
+
|
|
297
|
+
## ๐ Links
|
|
298
|
+
|
|
299
|
+
- [SiliconFlow Documentation](https://docs.siliconflow.cn)
|
|
300
|
+
- [SiliconFlow API Reference](https://docs.siliconflow.cn/cn/api-reference/images/images-generations)
|
|
301
|
+
- [MCP Specification](https://modelcontextprotocol.io)
|
|
302
|
+
- [Report Issues](https://github.com/martianzhang/siliconflow-image-mcp/issues)
|
|
303
|
+
|
|
304
|
+
---
|
|
305
|
+
|
|
306
|
+
**Made with โค๏ธ for the AI community - With special support for China users**
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
#!/usr/bin/env sh
|
|
2
|
+
# SiliconFlow Image MCP - Unix/Linux/macOS wrapper script
|
|
3
|
+
# Handles both local development and global installation
|
|
4
|
+
# For Windows, use the siliconflow-image-mcp.cmd wrapper
|
|
5
|
+
|
|
6
|
+
# Get the real directory of this script (resolves symlinks)
|
|
7
|
+
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
|
|
8
|
+
# If we're in a symlinked location, follow it to find the real package location
|
|
9
|
+
if [ -L "$0" ]; then
|
|
10
|
+
SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "$0")")" && pwd)"
|
|
11
|
+
fi
|
|
12
|
+
|
|
13
|
+
# Check if we're in a development environment (source files exist)
|
|
14
|
+
if [ -f "$SCRIPT_DIR/../src/index.ts" ]; then
|
|
15
|
+
# Development mode - run TypeScript source directly
|
|
16
|
+
exec tsx "$SCRIPT_DIR/../src/index.ts"
|
|
17
|
+
elif [ -f "$SCRIPT_DIR/../dist/index.js" ]; then
|
|
18
|
+
# Production mode - run compiled JavaScript
|
|
19
|
+
exec node "$SCRIPT_DIR/../dist/index.js"
|
|
20
|
+
else
|
|
21
|
+
echo "โ Error: Could not find siliconflow-image-mcp source files"
|
|
22
|
+
echo "Searched in: $SCRIPT_DIR/../src/index.ts and $SCRIPT_DIR/../dist/index.js"
|
|
23
|
+
exit 1
|
|
24
|
+
fi
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
@echo off
|
|
2
|
+
REM SiliconFlow Image MCP - Windows wrapper script
|
|
3
|
+
REM Handles both local development and global installation on Windows
|
|
4
|
+
|
|
5
|
+
setlocal
|
|
6
|
+
|
|
7
|
+
REM Get the directory where this script is located
|
|
8
|
+
set "SCRIPT_DIR=%~dp0"
|
|
9
|
+
|
|
10
|
+
REM Check if we're in a development environment (source files exist)
|
|
11
|
+
if exist "%SCRIPT_DIR%..\src\index.ts" (
|
|
12
|
+
REM Development mode - run TypeScript source directly
|
|
13
|
+
npx tsx "%SCRIPT_DIR%..\src\index.ts" %*
|
|
14
|
+
) else if exist "%SCRIPT_DIR%..\dist\index.js" (
|
|
15
|
+
REM Production mode - run compiled JavaScript
|
|
16
|
+
node "%SCRIPT_DIR%..\dist\index.js" %*
|
|
17
|
+
) else (
|
|
18
|
+
echo โ Error: Could not find siliconflow-image-mcp source files
|
|
19
|
+
echo Searched in: %SCRIPT_DIR%..\src\index.ts and %SCRIPT_DIR%..\dist\index.js
|
|
20
|
+
exit /b 1
|
|
21
|
+
)
|
package/dist/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 SiliconFlow Image MCP Contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/dist/README.md
ADDED
|
@@ -0,0 +1,306 @@
|
|
|
1
|
+
# SiliconFlow Image MCP
|
|
2
|
+
|
|
3
|
+
A Model Context Protocol (MCP) server for image generation and editing using **SiliconFlow** - optimized for China users with fast, reliable access.
|
|
4
|
+
|
|
5
|
+
## โจ Features
|
|
6
|
+
|
|
7
|
+
- ๐จ๐ณ **China Optimized** - Fast, reliable access from mainland China without VPN
|
|
8
|
+
- ๐ผ๏ธ **Image Generation** - Generate stunning images from text prompts
|
|
9
|
+
- โ๏ธ **Image Editing** - Edit existing images with AI-powered modifications
|
|
10
|
+
- ๐ **Model Discovery** - Browse available image generation models
|
|
11
|
+
- ๐ **Multiple Formats** - Support for various aspect ratios and resolutions
|
|
12
|
+
- ๐ **Easy Integration** - Simple setup with Claude Desktop and other MCP clients
|
|
13
|
+
- โก **Advanced Options** - Negative prompts, seeds, CFG values
|
|
14
|
+
- ๐ฅ๏ธ **Cross-Platform** - Native support for Linux, macOS, and Windows
|
|
15
|
+
- ๐ **Custom Storage** - Configure where images are saved via environment variable
|
|
16
|
+
- ๐งช **Mock Mode** - Test without making real API calls
|
|
17
|
+
|
|
18
|
+
## ๐ฆ Installation
|
|
19
|
+
|
|
20
|
+
### Using NPX (Recommended)
|
|
21
|
+
```bash
|
|
22
|
+
# No installation needed - use directly via npx
|
|
23
|
+
npx siliconflow-image-mcp
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
### Global Install
|
|
27
|
+
```bash
|
|
28
|
+
npm install -g siliconflow-image-mcp
|
|
29
|
+
siliconflow-image-mcp
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## โ๏ธ Setup
|
|
33
|
+
|
|
34
|
+
### 1. Get SiliconFlow API Key
|
|
35
|
+
- Visit [SiliconFlow Console](https://siliconflow.cn)
|
|
36
|
+
- Create an account and get your API key
|
|
37
|
+
- The service is optimized for China network conditions
|
|
38
|
+
|
|
39
|
+
### 2. Configure Environment
|
|
40
|
+
```bash
|
|
41
|
+
export SILICONFLOW_API_KEY="your-siliconflow-api-key"
|
|
42
|
+
|
|
43
|
+
# Optional: Custom directory for saved images (default: system temp dir)
|
|
44
|
+
export SILICONFLOW_IMAGE_DIR="/path/to/your/images"
|
|
45
|
+
|
|
46
|
+
# Optional: Mock mode for testing (no real API calls)
|
|
47
|
+
export SILICONFLOW_MOCK="true"
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### 3. Claude Desktop Configuration
|
|
51
|
+
|
|
52
|
+
Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{
|
|
56
|
+
"mcpServers": {
|
|
57
|
+
"siliconflow-image-mcp": {
|
|
58
|
+
"command": "npx",
|
|
59
|
+
"args": ["-y", "siliconflow-image-mcp"],
|
|
60
|
+
"env": {
|
|
61
|
+
"SILICONFLOW_API_KEY": "your-siliconflow-key",
|
|
62
|
+
"SILICONFLOW_IMAGE_DIR": "/path/to/save/images"
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
**Restart Claude Desktop** after adding the configuration.
|
|
70
|
+
|
|
71
|
+
## ๐ ๏ธ Available Tools
|
|
72
|
+
|
|
73
|
+
### 1. `generate_image`
|
|
74
|
+
Generate images from text descriptions.
|
|
75
|
+
|
|
76
|
+
**Parameters:**
|
|
77
|
+
- `prompt` (required): Detailed description of the image to generate
|
|
78
|
+
- `model` (optional): Model ID (default: `black-forest-labs/FLUX.1-dev`)
|
|
79
|
+
- `aspectRatio` (optional): Aspect ratio - `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`
|
|
80
|
+
- `imageSize` (optional): Image size - `1K`, `2K`, `4K`
|
|
81
|
+
- `count` (optional): Number of images (1-4, default: 1)
|
|
82
|
+
- `negativePrompt` (optional): What to avoid in the image
|
|
83
|
+
- `seed` (optional): Seed for reproducible results
|
|
84
|
+
|
|
85
|
+
**Example:**
|
|
86
|
+
```
|
|
87
|
+
Generate a beautiful sunset over mountains with a lake in the foreground,
|
|
88
|
+
in 16:9 aspect ratio, 4K resolution
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### 2. `edit_image`
|
|
92
|
+
Edit existing images with AI instructions.
|
|
93
|
+
|
|
94
|
+
**Parameters:**
|
|
95
|
+
- `image` (required): Base64 encoded image data or image URL
|
|
96
|
+
- `prompt` (required): Instructions for editing
|
|
97
|
+
- `model` (optional): Model ID (default: `Qwen/Qwen-Image-Edit-2509`)
|
|
98
|
+
|
|
99
|
+
**Example:**
|
|
100
|
+
```
|
|
101
|
+
Edit this image to make it brighter and increase the saturation
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
### 3. `list_image_models`
|
|
105
|
+
List all available image generation models.
|
|
106
|
+
|
|
107
|
+
**Parameters:** None
|
|
108
|
+
|
|
109
|
+
**Example:**
|
|
110
|
+
```
|
|
111
|
+
Show me available image generation models
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## ๐ก Usage Examples
|
|
115
|
+
|
|
116
|
+
### Basic Image Generation
|
|
117
|
+
```
|
|
118
|
+
Generate an image of a futuristic cityscape at night with neon lights
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### Multiple Images
|
|
122
|
+
```
|
|
123
|
+
Generate 3 different variations of a cute cat wearing a hat
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### Specific Aspect Ratio
|
|
127
|
+
```
|
|
128
|
+
Create a portrait of a wizard in 9:16 aspect ratio for mobile wallpaper
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### High Resolution
|
|
132
|
+
```
|
|
133
|
+
Generate a detailed landscape in 4K resolution with 16:9 aspect ratio
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
### Image Editing
|
|
137
|
+
```
|
|
138
|
+
Edit this image to make it look like a vintage photograph from the 1950s
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
### Advanced Options
|
|
142
|
+
```
|
|
143
|
+
Generate a photorealistic portrait using black-forest-labs/FLUX.1-dev
|
|
144
|
+
with negative prompt "blurry, low quality" and seed 12345
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
## ๐ง Model Recommendations
|
|
148
|
+
|
|
149
|
+
### SiliconFlow Models
|
|
150
|
+
- `black-forest-labs/FLUX.1-dev` - High quality general purpose (default)
|
|
151
|
+
- `Qwen/Qwen-Image-Edit-2509` - Excellent for image editing (default)
|
|
152
|
+
- `Kwai-Kolors/Kolors` - Good for artistic styles
|
|
153
|
+
- `stabilityai/stable-diffusion-xl-base-1.0` - Classic stable diffusion
|
|
154
|
+
|
|
155
|
+
## ๐ China-Specific Benefits
|
|
156
|
+
|
|
157
|
+
### SiliconFlow Advantages:
|
|
158
|
+
- โ
**Fast access** from mainland China
|
|
159
|
+
- โ
**Stable connection** without VPN
|
|
160
|
+
- โ
**Chinese language support**
|
|
161
|
+
- โ
**Local payment methods**
|
|
162
|
+
- โ
**Optimized infrastructure**
|
|
163
|
+
|
|
164
|
+
### Network Performance:
|
|
165
|
+
- Average response time: < 2 seconds from China
|
|
166
|
+
- 99.9% uptime from Chinese networks
|
|
167
|
+
- No Great Firewall interference
|
|
168
|
+
|
|
169
|
+
## ๐ง Environment Variables
|
|
170
|
+
|
|
171
|
+
| Variable | Required | Default | Description |
|
|
172
|
+
|----------|----------|---------|-------------|
|
|
173
|
+
| `SILICONFLOW_API_KEY` | **Yes** | - | Your SiliconFlow API key from [siliconflow.cn](https://siliconflow.cn) |
|
|
174
|
+
| `SILICONFLOW_IMAGE_DIR` | No | System temp dir | Custom directory to save generated/edited images |
|
|
175
|
+
| `SILICONFLOW_MOCK` | No | `false` | Enable mock mode for testing (no real API calls) |
|
|
176
|
+
|
|
177
|
+
### Examples
|
|
178
|
+
|
|
179
|
+
**Linux/macOS:**
|
|
180
|
+
```bash
|
|
181
|
+
export SILICONFLOW_API_KEY="sk-xxxxx"
|
|
182
|
+
export SILICONFLOW_IMAGE_DIR="/home/user/siliconflow-images"
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
**Windows CMD:**
|
|
186
|
+
```cmd
|
|
187
|
+
set SILICONFLOW_API_KEY=sk-xxxxx
|
|
188
|
+
set SILICONFLOW_IMAGE_DIR=C:\Users\MyUser\Images
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
**Windows PowerShell:**
|
|
192
|
+
```powershell
|
|
193
|
+
$env:SILICONFLOW_API_KEY="sk-xxxxx"
|
|
194
|
+
$env:SILICONFLOW_IMAGE_DIR="C:\Users\MyUser\Images"
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
## ๐ Security
|
|
198
|
+
|
|
199
|
+
- **API Key**: Your API keys are stored securely in environment variables
|
|
200
|
+
- **Input Validation**: All inputs are validated using Zod schemas
|
|
201
|
+
- **Rate Limiting**: Respect service provider limits
|
|
202
|
+
- **Content Filtering**: Consider implementing content policies for your use case
|
|
203
|
+
- **File Storage**: Images are saved to your specified directory or system temp
|
|
204
|
+
|
|
205
|
+
## ๐ Troubleshooting
|
|
206
|
+
|
|
207
|
+
### "No API key provided"
|
|
208
|
+
Make sure you've set the environment variable:
|
|
209
|
+
```bash
|
|
210
|
+
export SILICONFLOW_API_KEY="your-key"
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
### "Failed to connect to SiliconFlow"
|
|
214
|
+
- Check your API key is valid
|
|
215
|
+
- Verify network connectivity to `api.siliconflow.cn`
|
|
216
|
+
- Check SiliconFlow service status
|
|
217
|
+
|
|
218
|
+
### "No images were generated"
|
|
219
|
+
- Try a more descriptive prompt
|
|
220
|
+
- Check if the model supports image generation
|
|
221
|
+
- Verify your API key has access to the model
|
|
222
|
+
|
|
223
|
+
### Images not appearing in Claude
|
|
224
|
+
- Restart Claude Desktop after configuration changes
|
|
225
|
+
- Check the MCP server logs for errors
|
|
226
|
+
- Verify the server is running with `npm start`
|
|
227
|
+
|
|
228
|
+
### Images saved to wrong location
|
|
229
|
+
- Set `SILICONFLOW_IMAGE_DIR` to your desired path
|
|
230
|
+
- Ensure the directory exists and is writable
|
|
231
|
+
- Default location: system temp directory (`/tmp/siliconflow-images/` on Linux/macOS)
|
|
232
|
+
|
|
233
|
+
### Running on Windows
|
|
234
|
+
- Use the `.cmd` wrapper automatically provided by npm
|
|
235
|
+
- Or use Git Bash/WSL for Unix-style commands
|
|
236
|
+
- For native CMD/PowerShell, the `.cmd` file handles execution
|
|
237
|
+
|
|
238
|
+
## ๐ฐ Pricing
|
|
239
|
+
|
|
240
|
+
### SiliconFlow:
|
|
241
|
+
- **FLUX.1-dev**: ~ยฅ0.02-0.05 per image
|
|
242
|
+
- **Qwen-Image**: ~ยฅ0.01-0.03 per image
|
|
243
|
+
- **Kolors**: ~ยฅ0.01-0.02 per image
|
|
244
|
+
- **Free tier**: Available for new users
|
|
245
|
+
|
|
246
|
+
*Check [SiliconFlow pricing](https://siliconflow.cn/pricing) for current rates.*
|
|
247
|
+
|
|
248
|
+
## ๐ Development
|
|
249
|
+
|
|
250
|
+
### Local Development
|
|
251
|
+
```bash
|
|
252
|
+
# Clone the repository
|
|
253
|
+
git clone https://github.com/martianzhang/siliconflow-image-mcp.git
|
|
254
|
+
cd siliconflow-image-mcp
|
|
255
|
+
|
|
256
|
+
# Install dependencies
|
|
257
|
+
npm install
|
|
258
|
+
|
|
259
|
+
# Build the project
|
|
260
|
+
npm run build
|
|
261
|
+
|
|
262
|
+
# Run tests
|
|
263
|
+
npm test
|
|
264
|
+
|
|
265
|
+
# Start the server
|
|
266
|
+
npm start
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
### Project Structure
|
|
270
|
+
```
|
|
271
|
+
src/
|
|
272
|
+
โโโ index.ts # Main server entry
|
|
273
|
+
โโโ tools/
|
|
274
|
+
โ โโโ generate.ts # Image generation tool
|
|
275
|
+
โ โโโ edit.ts # Image editing tool
|
|
276
|
+
โ โโโ list-models.ts # Model discovery tool
|
|
277
|
+
โโโ services/
|
|
278
|
+
โ โโโ siliconflow.ts # SiliconFlow service wrapper
|
|
279
|
+
โโโ types/
|
|
280
|
+
โโโ index.ts # Type definitions
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
## ๐ค Contributing
|
|
284
|
+
|
|
285
|
+
Contributions are welcome! Please feel free to submit a Pull Request.
|
|
286
|
+
|
|
287
|
+
1. Fork the repository
|
|
288
|
+
2. Create a feature branch
|
|
289
|
+
3. Make your changes
|
|
290
|
+
4. Add tests for new functionality
|
|
291
|
+
5. Submit a pull request
|
|
292
|
+
|
|
293
|
+
## ๐ License
|
|
294
|
+
|
|
295
|
+
MIT License - see [LICENSE](LICENSE) for details.
|
|
296
|
+
|
|
297
|
+
## ๐ Links
|
|
298
|
+
|
|
299
|
+
- [SiliconFlow Documentation](https://docs.siliconflow.cn)
|
|
300
|
+
- [SiliconFlow API Reference](https://docs.siliconflow.cn/cn/api-reference/images/images-generations)
|
|
301
|
+
- [MCP Specification](https://modelcontextprotocol.io)
|
|
302
|
+
- [Report Issues](https://github.com/martianzhang/siliconflow-image-mcp/issues)
|
|
303
|
+
|
|
304
|
+
---
|
|
305
|
+
|
|
306
|
+
**Made with โค๏ธ for the AI community - With special support for China users**
|