# DeepKolor MCP

Use [DeepKolor](https://deepkolor.ai) from Cursor, Claude, and other MCP-compatible clients to create AI images and videos through a small set of predictable tools.

DeepKolor is a conversational visual creation platform for AI image generation, photo editing, product photography, advertising creatives, portraits, posters, and video generation. The public [DeepKolor Agent Skills](https://github.com/DeepKolor/deepkolor-agent-skills) help an agent choose the right visual workflow; this MCP server executes the final image or video task.

Visit [https://deepkolor.ai](https://deepkolor.ai) to try the full visual creation experience, explore image and video workflows, and create an API key for MCP access.

## Why DeepKolor MCP

- Turn a prompt into a production-ready AI image or video task.
- Use the same DeepKolor generation infrastructure behind the web product.
- Keep prompts and visual workflows in your preferred AI client.
- Retrieve generated media through a stable asynchronous task API.

The server is a thin MCP adapter. Generation, API key validation, credits, moderation, provider calls, task ownership, and storage remain in DeepKolor.

## Tools

- `generate_image`
- `generate_video`
- `get_task`

Generation is asynchronous. Call `get_task` with the returned `task_id` to retrieve the result URL.

## Typical workflows

### Product photography

Use `generate_image` for marketplace hero images, product lifestyle scenes, listing galleries, and e-commerce visuals. For workflow guidance, install the `ecommerce-image-agent` skill from [DeepKolor Agent Skills](https://github.com/DeepKolor/deepkolor-agent-skills).

### Photo editing

Pass one or more public HTTPS image URLs to `generate_image` with `image-to-image` for controlled edits, background changes, or visual refinement.

### AI video generation

Use `generate_video` for text-to-video or image-to-video workflows. The task returns immediately; poll with `get_task` until the video URL is available.

For the complete set of DeepKolor tools and visual workflows, start at [deepkolor.ai](https://deepkolor.ai).

## Open Plugins

This repository is an [Agent Plugins / Open Plugins](https://open-plugins.com) package. Compatible clients discover the plugin manifest in `plugin.json` and the remote MCP server declaration in `mcp.json`.

The bundled configuration connects to the local Streamable HTTP server:

```json
{
  "type": "streamable-http",
  "url": "http://127.0.0.1:8787/mcp"
}
```

Start the server with `pnpm build && pnpm start` before loading the plugin. Authentication is client-managed: set `DEEPKOLOR_API_KEY` for a local single-account server, or send `Authorization: Bearer sk_...` from a client that supports per-request credentials. Do not add an API key or any other secret to `mcp.json`.

### Use a deployed server

For an HTTPS deployment, replace the local URL in `mcp.json` with the public Streamable HTTP endpoint:

```json
{
  "type": "streamable-http",
  "url": "https://your-deployment.example/mcp"
}
```

## Run locally

```bash
cp .env.example .env
pnpm install
pnpm build
pnpm start
```

The MCP endpoint is `http://127.0.0.1:8787/mcp` by default.

For a local single-account server, set `DEEPKOLOR_API_KEY` to an API key created in DeepKolor settings. For a shared remote server, MCP clients should send `Authorization: Bearer sk_...`; the server forwards that key per request. Never put Provider keys in this project.

## Remote deployment

Deploy this server behind HTTPS and expose `/mcp`. Configure:

- `DEEPKOLOR_API_URL`
- `DEEPKOLOR_API_KEY`
- `MCP_HOST`
- `MCP_PORT`

The configured DeepKolor API key identifies the account used for all tool calls. Do not log it.