# agnes-image-mcp-server

[![npm version](https://img.shields.io/npm/v/agnes-image-mcp-server.svg)](https://www.npmjs.com/package/agnes-image-mcp-server)
[![Downloads](https://img.shields.io/npm/dm/agnes-image-mcp-server.svg)](https://www.npmjs.com/package/agnes-image-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![node](https://img.shields.io/node/v/agnes-image-mcp-server.svg)](https://nodejs.org)

MCP server for image generation using the **Agnes Image 2.1 Flash** model.

![Example output generated by this server](./assets/example.webp)

*Image generated with `generate_image`, prompt: "Vibrant digital illustration of a friendly retro-futuristic robot artist in a neon-lit studio…", size `2K`, ratio `16:9`.*

## Example session

```
> generate_image
  { "prompt": "A red fox astronaut drifting through a pastel nebula",
    "size": "2K", "ratio": "16:9" }

  Image generated successfully.
  URL: https://platform-outputs.agnes-ai.space/images/t2i/…/output_….png
```

When the API returns inline base64 instead of a URL, the tool responds with an
MCP `image` content block that clients render directly.

## Quick start

Get an API key at [agnes-ai.com](https://www.agnes-ai.com), then add the server to your MCP client config (ZCode, Claude Desktop, Cursor, etc.) — no install needed, `npx` fetches it:

```json
{
  "mcpServers": {
    "agnes-image": {
      "command": "npx",
      "args": ["-y", "agnes-image-mcp-server"],
      "env": {
        "AGNES_API_KEY": "your-key-here"
      }
    }
  }
}
```

## Development

```bash
git clone <repo-url>
cd agnes-image-mcp
npm install
npm run build
npm start        # runs dist/index.js over stdio
```

## Tools

### `generate_image`

Generate an image from a text prompt.

| Parameter        | Type   | Required | Description                                              |
|------------------|--------|----------|----------------------------------------------------------|
| `prompt`         | string | Yes      | Text description of the image                            |
| `size`           | enum   | No       | `1K` (default), `2K`, or `4K`                            |
| `ratio`          | enum   | No       | `1:1` (default), `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3` |
| `negative_prompt`| string | No       | Things to avoid in the image                             |

Returns the generated image as a URL or base64-encoded PNG.

### `list_image_options`

List available sizes and aspect ratios.

## API Reference

- Docs: https://www.agnes-ai.com/en/docs/agnes-image-21-flash
- Base URL: `https://apihub.agnes-ai.com`
- Endpoint: `POST /v1/images/generations`