Jsoncut MCP Server
OfficialClick on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Jsoncut MCP Server create an image config with a sunset background and inspirational quote"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
โ ๏ธ OUTDATED REPOSITORY - This repository is no longer maintained
A public MCP server is now available and this package is deprecated.
Please use the official public server instead: https://mcp.jsoncut.com/mcp
For more information, see: https://docs.jsoncut.com/docs/mcp/overview
๐ Features
๐จ Image Generation: Create JSON configurations for image composition with layers, positioning, and effects
๐ฌ Video Generation: Create JSON configurations for video rendering with clips, transitions, and audio
โ Configuration Validation: Validate configs against the Jsoncut API before submission
๐ Schema Resources: JSON schemas automatically available as MCP resources
๐ Flexible Authentication: API key via environment variable or .env file
Related MCP server: CapCut & Google Flow MCP
๐ฆ Quick Start
Using npx (Recommended for Local)
export JSONCUT_API_KEY=your_api_key_here
npx -y @jsoncut/mcp-serverUsing Remote Server (Recommended)
A public MCP server is available at https://mcp.jsoncut.com. No installation needed - just configure your MCP client with your API key:
{
"jsoncut": {
"url": "https://mcp.jsoncut.com/mcp",
"headers": {
"x-api-key": "your_jsoncut_api_key_here"
}
}
}Using Docker Locally (Optional)
You can also run your own local server using Docker:
# Pull and run from Docker Hub
docker run -d \
--name jsoncut-mcp \
-p 3210:3000 \
centerbit/jsoncut-mcp-server:latest
# Access at: http://localhost:3210/mcpOr use Docker Compose:
# Start the service
docker-compose up -d
# Access at: http://localhost:3210/mcp๐ See DOCKER.md for complete Docker deployment guide
Get Your API Key
Get your Jsoncut API key at jsoncut.com
# Set as environment variable
export JSONCUT_API_KEY=your_api_key_here
# Or create .env file
cp .env.example .env
# Edit .env and add: JSONCUT_API_KEY=your_api_key_here๐ฏ MCP Client Configuration
Remote Server (Recommended)
Use the public server at https://mcp.jsoncut.com:
Cursor IDE
Open Cursor Settings โ Features โ MCP Servers โ "+ Add New MCP Server"
{
"jsoncut": {
"url": "https://mcp.jsoncut.com/mcp",
"headers": {
"X-API-Key": "your_jsoncut_api_key_here"
}
}
}Claude Desktop
Add to your claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"jsoncut": {
"url": "https://mcp.jsoncut.com/mcp",
"headers": {
"X-API-Key": "your_jsoncut_api_key_here"
}
}
}
}Local npx Mode
For local development without network access:
Cursor IDE
{
"jsoncut": {
"command": "npx",
"args": ["-y", "@jsoncut/mcp-server"],
"env": {
"JSONCUT_API_KEY": "your_api_key_here"
}
}
}Claude Desktop
{
"mcpServers": {
"jsoncut": {
"command": "npx",
"args": ["-y", "@jsoncut/mcp-server"],
"env": {
"JSONCUT_API_KEY": "your_api_key_here"
}
}
}
}Local Docker Server
If you're running your own local Docker server:
Cursor IDE
{
"jsoncut": {
"url": "http://localhost:3210/mcp",
"headers": {
"X-API-Key": "your_jsoncut_api_key_here"
}
}
}Claude Desktop
{
"mcpServers": {
"jsoncut": {
"url": "http://localhost:3210/mcp",
"headers": {
"X-API-Key": "your_jsoncut_api_key_here"
}
}
}
}๐ MCP Resources
The server automatically exposes JSON schemas as MCP resources:
schema://image- Complete image generation schemaschema://video- Complete video generation schema
AI agents can read these directly without tool calls for fast access to all configuration options.
๐ ๏ธ Available Tools
create_image_config
Create JSON configurations for image generation with a layer-based system.
Layer Types:
image: Display images with fit modes (cover, contain, fill, inside, outside)
text: Text with custom fonts, alignment, wrapping, and effects
rectangle: Rectangular shapes with fill, stroke, and rounded corners
circle: Circular and elliptical shapes
gradient: Linear or radial color gradients
Positioning:
Pixel coordinates:
{ x: 100, y: 50 }Position strings:
center,top,bottom,top-left,top-right, etc.Position objects:
{ x: 0.5, y: 0.5, originX: "center", originY: "center" }
Example:
{
"width": 1200,
"height": 630,
"layers": [
{
"type": "gradient",
"x": 0, "y": 0, "width": 1200, "height": 630,
"gradient": {
"type": "linear",
"colors": ["#667eea", "#764ba2"],
"direction": "diagonal"
}
},
{
"type": "text",
"text": "Welcome to Jsoncut",
"position": "center",
"fontSize": 64,
"color": "#ffffff"
}
]
}create_video_config
Create JSON configurations for video generation with clips, layers, and transitions.
Key Features:
Clips: Sequential video segments with individual layers
Layer Types: video, image, title, subtitle, news-title, audio, gradients, and more
Transitions: 75+ effects (fade, wipe, circle, cube, glitch, zoom, etc.)
Audio: Background music, multiple tracks, normalization, and ducking
Example:
{
"width": 1920,
"height": 1080,
"fps": 30,
"defaults": {
"duration": 3,
"transition": { "name": "fade", "duration": 1 }
},
"clips": [
{
"layers": [
{ "type": "title", "text": "Welcome", "position": "center" }
]
}
]
}validate_config
Validate configurations against the Jsoncut API before submission.
Parameters:
type: "image" or "video"config: Configuration object to validateapiKey: Optional API key (uses environment if not provided)
Returns:
Validation status
Estimated token cost
Error details (if any)
Detected resources with sizes
get_image_schema / get_video_schema
Get complete JSON schemas for image or video generation.
Note: Schemas are also available as MCP resources (schema://image and schema://video) which AI agents can access directly without tool calls.
๐ Workflow
Create Configuration: Use
create_image_configorcreate_video_configValidate (optional): Call
validate_configif you have actual file pathsSubmit: Use the configuration with the Jsoncut API
The schemas are automatically available as MCP resources, so AI agents have instant access to all configuration options.
๐ File Paths
Use placeholder paths in configurations:
/image/2024-01-15/userXXX/photo.jpg
/video/2024-01-15/userXXX/video.mp4
/audio/2024-01-15/userXXX/music.mp3
/font/2024-01-15/userXXX/CustomFont.ttfSupported formats:
Images: png, jpg, jpeg, gif, webp
Videos: mp4, mov, avi, webm
Audio: mp3, wav, m4a, aac
Fonts: ttf, otf, woff, woff2
๐งช Testing
Use the MCP Inspector for interactive testing:
export JSONCUT_API_KEY=your_api_key_here
npm run inspector๐ง Development
Local Development
# Clone and install
git clone https://github.com/jsoncut/jsoncut-mcp-server.git
cd jsoncut-mcp-server
npm install
# Build
npm run build
# Watch mode
npm run watch
# Run locally
node dist/index.jsConfiguration with Local Build
For Cursor/Claude Desktop, use the local build:
{
"jsoncut": {
"command": "node",
"args": ["/absolute/path/to/jsoncut-mcp-server/dist/index.js"],
"env": {
"JSONCUT_API_KEY": "your_api_key_here"
}
}
}๐ Examples
See the examples/ directory for complete configurations:
image-example.json- Image generation with multiple layer typesvideo-example.json- Video generation with clips and transitions
๐ค Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
๐ License
MIT License - see LICENSE file for details.
๐ Links
API Documentation: docs.jsoncut.com
Website: jsoncut.com
npm: @jsoncut/mcp-server
Support: support@jsoncut.com
Available Tools
5 toolscreate_image_configA
Create a JSON configuration for image generation based on jsoncut documentation.
Returns a complete configuration object that can be used with the validate_config tool or submitted directly to the jsoncut API.
WORKFLOW:
First get the schema (read resource schema://image or call get_image_schema) to understand all available options
Create the configuration with this tool
Call validate_config to verify the configuration (if user provided media file paths)
Image Structure:
Layer-based system (rendered bottom to top, max 50 layers)
Canvas with dimensions, background color, and output format
Support for defaults to avoid repetition
Layer Types:
image: Display uploaded images with fit modes (cover, contain, fill, inside, outside)
text: Text with custom fonts, alignment, wrapping, and effects
rectangle: Rectangular shapes with fill, stroke, and rounded corners
circle: Circular and elliptical shapes
gradient: Linear or radial color gradients
Positioning Options:
x, y coordinates (pixels from top-left)
position strings: center, top, bottom, top-left, top-right, center-left, center-right, bottom-left, bottom-right
position objects: { x: 0-1, y: 0-1, originX: left|center|right, originY: top|center|bottom }
Visual Effects:
opacity: 0-1 transparency
rotation: degrees
blur: pixel radius
borderRadius: rounded corners (image, rectangle)
Text Features:
Custom fonts via fontPath or Google Fonts via googleFont (format: 'FontName:weight' e.g. 'Roboto:600')
Text wrapping with width and lineHeight
Alignment: left, center, right
backgroundColor (single line only)
Output Formats:
png: Lossless with transparency (default)
jpeg: Lossy compression (use quality parameter)
webp: Modern format with transparency and compression
Defaults System:
defaults.layer: Properties for all layers
defaults.layerType.{type}: Properties for specific layer types
File paths should be placeholders like "/image/2024-01-15/userXXX/filename.ext" or "/font/2024-01-15/userXXX/font.ttf".
Inputs: layers (required), width, height, backgroundColor, +3 more.
create_video_configA
Create a JSON configuration for video generation based on jsoncut documentation.
Returns a complete configuration object that can be used with the validate_config tool or submitted directly to the jsoncut API.
WORKFLOW:
First get the schema (read resource schema://video or call get_video_schema) to understand all available options
Create the configuration with this tool
Call validate_config to verify the configuration (if user provided media file paths)
Video Structure:
Built using clips (segments) that play sequentially
Each clip contains layers (rendered bottom to top)
Supports transitions between clips
Comprehensive audio system with multiple options
Layer Types:
video: Display video files with timing control, Ken Burns effects, and enhanced positioning
image: Static images with positioning and Ken Burns effects
image-overlay: Images positioned over other content with timing
title: Large headline text with animation styles (fade-in, word-by-word, letter-by-letter) and enhanced positioning
subtitle: Smaller text for captions
news-title: Breaking news style with colored backgrounds
title-background: Titles with full-screen backgrounds
slide-in-text: Animated text that slides in
audio: Audio tracks tied to clips (requires keepSourceAudio: true)
detached-audio: Audio with clip-relative timing
fill-color: Solid color backgrounds
linear-gradient: Linear gradient backgrounds
radial-gradient: Radial gradient backgrounds
rainbow-colors: Animated rainbow effects
pause: Black screen pauses
Audio Options:
audioFilePath + loopAudio: Background music throughout video
audioTracks: Multiple audio tracks with independent timing
audioNorm: Audio normalization with ducking
keepSourceAudio: Keep audio from video layers
Audio layers within clips
Video & title layer Positioning:
Position objects: { x: 0-1, y: 0-1, originX: left|center|right, originY: top|center|bottom }
Position strings: center, top, bottom, top-left, top-right, center-left, center-right, bottom-left, bottom-right
Video layers support both position objects and strings
Title layers support enhanced positioning with position objects
Title Layer Animation Styles:
fade-in: Smooth fade-in effect (default)
word-by-word: Words appear sequentially
letter-by-letter: Letters appear sequentially
Zoom effects automatically disabled for word-by-word and letter-by-letter styles
Transitions: 75+ transition effects including fade, wipe, circle, cube, glitch, zoom, etc.
File paths should be placeholders like "/input/userXXX/filename.ext".
Inputs: clips (required), width, height, fps, +10 more.
get_image_schemaA
Get the complete JSON schema for image generation.
Returns the full JSON Schema document that defines all possible configuration options for image generation jobs. Use this to understand all available options, constraints, and examples.
NOTE: This schema is also available as a resource at schema://image which can be read directly without a tool call.
IMPORTANT: Get this schema FIRST when creating image configurations to understand the complete structure, available layer types, positioning options, and all properties. This ensures you create valid and complete configurations.
Inputs: no named parameters.
get_video_schemaA
Get the complete JSON schema for video generation.
Returns the full JSON Schema document that defines all possible configuration options for video generation jobs. Use this to understand all available options, constraints, and examples.
NOTE: This schema is also available as a resource at schema://video which can be read directly without a tool call.
IMPORTANT: Get this schema FIRST when creating video configurations to understand the complete structure, available layer types, audio options, transitions, and all properties. This ensures you create valid and complete configurations.
Inputs: no named parameters.
validate_configA
Validate a job configuration against the jsoncut API.
This tool sends the configuration to the API's validation endpoint to check:
Schema compliance
Resource availability
Estimated token cost
Any configuration errors
WHEN TO USE:
ONLY call this tool if the user has provided actual media file paths (e.g., from uploaded files)
DO NOT validate configurations with placeholder paths like "/image/2024-01-15/userXXX/..."
Always call this after creating a configuration when real file paths are available
BENEFITS:
Catches errors before job submission
Provides accurate token cost estimates
Verifies that referenced files exist and are accessible
Inputs: type (required), config (required), apiKey.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose: two for image config/schema, two for video config/schema, and one for validation. No overlap in functionality.
All tool names follow a consistent verb_noun pattern in snake_case (create_, get_, validate_), with parallelism between image and video tools.
5 tools is well-scoped for the server's purpose of handling image and video configuration creation, schema retrieval, and validation. No extraneous tools.
Core workflow is covered: schema retrieval, config creation, and validation. Minor gaps include lack of a tool to submit jobs or manage existing configs, but these may be out of scope.
Maintenance
Related MCP Connectors
Build and run visual creative-production workflows from your AI agent.
Video, audio, and image processing for AI agents: convert, transcribe, upscale - 150+ operations.
AI image + video generation for agents: --flag prompt DSL, async generate/poll, x402 pay-per-use.
Generate and edit images, video, voice, lip-sync and 3D models from your AI agent.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to control Adobe After Effects to create videos programmatically, with commands for comps, layers, effects, and rendering.8 npm28MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to generate cinematic video and image assets and perform autonomous timeline assembly, multi-track audio editing, chroma-key compositing, and local draft manipulation from conversational prompts.3MIT

keyline-mcpofficial
FlicenseNot gradedqualityBmaintenanceEnables AI agents to author designs as structured JSON scenes and render them to PNG, JPEG, WebP, vector PDF, animated PNG, GIF, MP4 or WebM at every target size, using one native binary with no browser or headless Chrome.6-
DT.ly MCP Serverofficial
AlicenseNot gradedqualityBmaintenanceEnables AI agents to author and refine JSON-based motion-graphics compositions by editing layers, keyframes, easing curves, text animators, masks, effects, and other animation properties, then previewing rendered frames or video output.8 npmMIT