Quickstart

This page shows the minimum MCP setup that gets KPainter running inside an MCP-compatible client.

Step 1: Get an API Key

KPainter MCP uses the user's own API key.

Before you configure any client:

sign up or log in to KPainter
open the API Key page
activate and copy your API key
keep it ready for MCP client config

Step 2: Add a Local stdio MCP Server

For local MCP clients, stdio is the easiest path.

If kp-mcp is already available in your environment, a standard config looks like this:

{  "mcpServers": {    "kpainter": {      "command": "kp-mcp",      "env": {        "KGP_API_KEY": "<your_api_key>"      }    }  }}

If you are running from the kgp-service source tree instead, use:

{  "mcpServers": {    "kpainter": {      "command": "python",      "args": ["-m", "src.mcp_server"],      "cwd": "/path/to/kgp-service",      "env": {        "KGP_API_KEY": "<your_api_key>"      }    }  }}

Step 3: Validate the Key First

The CLI binary is kp-mcp.

The MCP tool names now use the kp_* prefix, so start with tools such as kp_me and kp_get_catalog.

Once the MCP server is connected, start with:

kp_me

Use it to confirm:

the key is valid
it belongs to the intended user
it can manage creations

Do not skip this and jump straight into creation.

Step 4: Read the Catalog

Call:

kp_get_catalog

Use it before choosing:

type
aspect_ratio
output_quality
voice_id
style_id
duration_seconds
scene_count

Do not guess these values.

Step 5: Create the First Result

A first happy-path workflow usually looks like this:

kp_me
kp_get_catalog
kp_create_creation
kp_get_job_status
kp_get_creation

For example, you can ask your MCP client to create something like:

Create a slide-based explainer video in English that explains how MCP works in 6 scenes.

The client should then map that request to the official type and parameters returned by kp_get_catalog.

Step 6: Read the Final Detail

When the job succeeds, read:

main_url
artifacts
scenes
editable_actions

from kp_get_creation.

This is the main place to read the finished result.

If You Need Scene-Level Editing

For supported types, inspect editable_actions and scenes first, then use:

kp_edit_scene

Current scene-edit actions are:

update_scene_narration
regenerate_scene

Treat edits as async too:

kp_edit_scene
kp_get_job_status
kp_get_creation