Content
# Tool List
[](https://www.npmjs.com/package/sensenova-u1-mcp)
[](https://www.npmjs.com/package/sensenova-u1-mcp)
[](LICENSE)
[](https://github.com/Microbiosis/sensenova-u1-mcp)
> SenseNova U1 Fast MCP Server -- Image generation service based on Model Context Protocol (MCP), access to SenseNova U1 Fast image generation API.
## Table of Contents
- [Features](#features)
- [Quick Start](#quick-start)
- [MCP Configuration](#mcp-configuration)
- [Tool Description](#tool-description)
- [API Reference](#api-reference)
- [Development Guide](#development-guide)
- [License](#license)
## Features
- AI Image Generation -- Call SenseNova U1 Fast image generation API through MCP protocol
- Chinese Support -- Fully support Chinese prompts, the more detailed the description, the better the effect
- 11 Resolutions -- Support 16:9 / 9:16 / 1:1 / 3:4 / 4:3 / 21:9 and other proportions
- Batch Generation -- Generate up to 4 images at a time
- Lightweight and Dependency-Free -- Pure native Fetch API, only depends on MCP SDK
## Quick Start
### Prerequisites
1. Register [SenseNova Platform](https://platform.sensenova.cn) and obtain API Key
2. Set environment variables:
```bash
# macOS / Linux
export SENSENOVA_API_KEY=sk-xxx
# Windows (CMD)
set SENSENOVA_API_KEY=sk-xxx
# Windows (PowerShell)
$env:SENSENOVA_API_KEY="sk-xxx"
```
### Installation
```bash
# Global installation
npm install -g sensenova-u1-mcp
# Or run directly (no installation required)
npx -y sensenova-u1-mcp
```
## MCP Configuration
### Claude Desktop / Cursor / VS Code / Cherry Studio
Add the following configuration to the MCP client configuration file:
```json
{
"mcpServers": {
"sensenova-u1-fast": {
"command": "npx",
"args": ["-y", "sensenova-u1-mcp"],
"env": {
"SENSENOVA_API_KEY": "sk-xxx"
}
}
}
}
```
Note: `command` must be `npx`, and `args` should not contain any local absolute paths to ensure portability.
## Tool Description
### `generate_image`
Generate an image using the SenseNova U1 Fast model.
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `prompt` | `string` | Yes | -- | Image description text, supports Chinese, maximum about 4096 tokens. The more detailed the description, the better the effect |
| `size` | `string` | No | `2752x1536` | Resolution, supports 11 sizes (see table below) |
| `n` | `integer` | No | `1` | Generation quantity, range 1~4 |
#### Supported Resolutions
| Size | Aspect Ratio | Applicable Scenario |
| --- | --- | --- |
| `1344x3136` | 9:21 | Ultra-long vertical screen |
| `1536x2752` | 9:16 | Mobile wallpaper/poster |
| `1664x2496` | 2:3 | Vertical infographic |
| `1760x2368` | 3:4 | Vertical card |
| `1824x2272` | 4:5 | Social media graphic |
| `2048x2048` | 1:1 | Square cover image |
| `2272x1824` | 5:4 | Horizontal card |
| `2368x1760` | 4:3 | Tablet/display |
| `2496x1664` | 3:2 | Horizontal poster |
| **`2752x1536`** | **16:9** | **Default, widescreen/infographic** |
| `3072x1376` | 21:9 | Ultra-wide screen |
### Prompt Example
A detailed prompt can generate a more accurate image. The following is a complete example structure:
```text
Theme: [Briefly describe the image theme]
Style: [Cartoon/realistic/flat/3D, etc.]
Color tone: [Main color tone description]
Layout: [Typesetting description]
Elements: [Key element list]
Text: [Text content to be included]
```
## API Reference
This service is based on the official SenseNova U1 Fast API:
```
POST https://token.sensenova.cn/v1/images/generations
```
| Parameter | Type | Required | Default |
| --- | --- | --- | --- |
| `model` | `string` | Yes | `sensenova-u1-fast` |
| `prompt` | `string` | Yes | -- |
| `size` | `string` | No | `2752x1536` |
| `n` | `integer` | No | `1` |
**Response Structure**:
```json
{
"created": 1713167890,
"data": [
{ "url": "https://cdn.sensenova.dev/gen/..." }
]
}
```
### Error Codes
| HTTP | Meaning | Handling Suggestion |
| --- | --- | --- |
| 400 | Invalid parameters | Check request parameters |
| 403 | Insufficient permissions | Check API Key |
| 429 | Quota exceeded | 1500 requests per 5 hours, try again later |
| 500 | Server error | Try again later |
## Development Guide
### Local Development
```bash
# Clone repository
git clone https://github.com/Microbiosis/sensenova-u1-mcp.git
cd sensenova-u1-mcp
# Install dependencies
npm install
# Set environment variables
export SENSENOVA_API_KEY=sk-xxx
# Run
node index.js
```
### Project Structure
```
sensenova-u1-mcp/
├── index.js # MCP server main entry
├── server.json # MCP Registry registration configuration
├── package.json
├── README.md
├── LICENSE # MIT license
├── .editorconfig # Editor code style configuration
├── .gitignore
└── .npmignore
```
### Publish to npm
```bash
# Update version number
npm version patch # 1.0.0 -> 1.0.1
npm version minor # 1.0.0 -> 1.1.0
npm version major # 1.0.0 -> 2.0.0
# Publish
npm publish
# Verify
npx -y sensenova-u1-mcp
```
## License
[MIT](LICENSE) (c) 2025 [redmingwei](https://github.com/Microbiosis)
