Content
# Jimeng AI Image Generation MCP Service V4.0
Based on the Volcano Engine Jimeng AI's image generation MCP (Model Context Protocol) service. The latest Jimeng image generation MCP servers support the latest Jimeng Seedream 4.0 model: jimeng_t2i_v40.
## Features
- Generate high-quality images using the Volcano Engine Jimeng AI API
- Supports multiple image aspect ratios: 4:3, 3:4, 16:9, 9:16
- Standardized MCP interface, compatible with various MCP clients
- Environment variable configuration, secure and convenient
## Installation Dependencies
```bash
cd jimeng-mcp-v4
npm install
```
## Build the Project
```bash
npm run build
```
## Environment Variable Configuration
Set the following environment variables:
```bash
export JIMENG_ACCESS_KEY="Your Volcano Engine Access Key"
export JIMENG_SECRET_KEY="Your Volcano Engine Secret Key"
```
### Obtain API Keys
1. Visit the [Volcano Engine Console](https://console.volcengine.com/)
2. After logging in, go to the "Jimeng AI" product page and activate the service (you can choose a free trial)
3. Create access keys on the "Access Control" page to obtain the Access Key and Secret Key
4. Ensure that your account has the permissions and policies related to Jimeng AI image generation enabled
**Note:** According to the official documentation, please ensure to use the correct req_key parameter value `jimeng_high_aes_general_v21_L`.
## Usage
### Method 1: Using npx (Recommended)
No installation required, directly use in the MCP client configuration:
**Configuration File Location:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
**Configuration Content:**
```json
{
"mcpServers": {
"jimeng-mcp-v4": {
"command": "npx",
"args": ["-y", "jimeng-mcp-v4@latest"],
"env": {
"JIMENG_ACCESS_KEY": "Your Access Key",
"JIMENG_SECRET_KEY": "Your Secret Key"
}
}
}
}
```
### Method 2: Global Installation
```bash
# Install
npm install -g jimeng-mcp-v4
# Use in configuration file
{
"mcpServers": {
"jimeng-mcp-v4": {
"command": "jimeng-mcp-v4",
"env": {
"JIMENG_ACCESS_KEY": "Your Access Key",
"JIMENG_SECRET_KEY": "Your Secret Key"
}
}
}
}
```
### Method 3: Local Development
```bash
# Clone the repository
git clone https://github.com/yo4ai/jimeng-mcp-v4.git
cd jimeng-mcp-v4
# Install dependencies and build
npm install
npm run build
# Use in configuration file
{
"mcpServers": {
"jimeng-mcp-v4": {
"command": "node",
"args": ["/path/to/jimeng-mcp-v4/build/index.js"],
"env": {
"JIMENG_ACCESS_KEY": "Your Access Key",
"JIMENG_SECRET_KEY": "Your Secret Key"
}
}
}
}
```
## API Interface
### generate-image
A tool used when the user needs to generate an image.
**Parameters:**
- `text` (string): The text that the user wants to display on the image
- `illustration` (string): Extract 3-5 keywords for illustration elements that can be used as embellishments based on the text the user wants to display
- `color` (string): The main background color of the image
- `ratio` (enum): Image aspect ratio, supports the following options:
- `"4:3"`: 512×384
- `"3:4"`: 384×512
- `"16:9"`: 512×288
- `"9:16"`: 288×512
**Prompt Generation Rules:**
The tool will automatically combine the input parameters into the following format for the prompt:
```
Font design: "{text}", black font, italic, with shadow. Clean background, gradient from white to {color}. Accented with light gray, semi-transparent {illustration} and other elements as embellishments.
```
**Returns:**
- On success, returns the image URL and details
- On failure, returns error information
## Usage Example
```typescript
// Call in MCP client
const result = await mcp.callTool('generate-image', {
text: 'Happy New Year',
illustration: 'fireworks, lanterns, auspicious clouds, stars, firecrackers',
color: 'red',
ratio: '4:3',
});
```
## Project Structure
```
jimeng-mcp-v4/
├── src/
│ └── index.ts # Main service file
├── build/ # Compilation output directory
├── package.json # Project configuration
├── tsconfig.json # TypeScript configuration
└── README.md # Project description
```
## Notes
1. Ensure that the network connection is stable and can access the Volcano Engine API
2. API calls consume credits, please monitor usage
3. The generated image URLs have a time limit, it is recommended to download and save them promptly
4. Please comply with the Volcano Engine's terms of use and Jimeng AI's content policies
## Troubleshooting
### Common Errors
1. **Environment Variables Not Set:** Ensure that the correct ACCESS_KEY and SECRET_KEY are set
2. **Network Connection Issues:** Check network connectivity and firewall settings
3. **Insufficient API Quota:** Check the balance and API call limits of your Volcano Engine account
4. **Prompt Non-compliance:** Ensure that the prompt complies with content safety regulations
### Debugging Methods
Add debugging information at runtime:
```bash
DEBUG=* node build/index.js
```
## License
ISC License
