Freepik Spaces MCP Server

Give Claude full control over Freepik Spaces — create nodes, connect workflows, generate images/videos/audio, and run production pipelines from natural language.

The first MCP server that lets AI agents build and execute visual AI workflows on Freepik's infinite canvas. Create persistent nodes, wire them together, and run generations — all programmatically.

---

What It Does

Claude can now:

• Create persistent nodes (Image Generator, Video Generator, Voice Generator, Text, Assistant) directly in Freepik Spaces
• Connect nodes with visual wires that render on the canvas
• Run generations natively using Freepik's own execution engine (107+ AI models)
• Build multi-angle UGC pipelines with character consistency across all outputs
• Generate voiceovers, music, and sound effects via ElevenLabs and Freepik Audio

All nodes persist across page reloads. All connections are visible as wires on the canvas. All generations use Freepik's native Run mechanism.

---

Architecture

Claude Code ──(MCP stdio, 29 tools)──> freepik_spaces_mcp/server.py
  |
  |-- Liveblocks WS injection ──> Persistent node/edge CRUD
  |   (addInitScript patches WebSocket constructor before page load,
  |    captures Liveblocks connection, sends type:4 create ops)
  |
  |-- Vue Flow API injection ──> Graph state read/write
  |   (#app.__vue_app__.config.globalProperties.$vueFlowStorage)
  |
  |-- Freepik Internal API ──> Native workflow execution
  |   POST /pikaso/api/spaces/{uuid}/workflows/execute
  |
  |-- Freepik REST API ──> Direct generation (131 endpoints)
  |   api.freepik.com/v1/ai/*
  |
  |-- Playwright CDP ──> Browser session management
      Attaches to user's logged-in Chrome via DevTools Protocol

Prerequisites

• Python 3.11+
• Google Chrome (for CDP attach mode)
• Freepik Premium+ account (for API access and Spaces)
• Freepik API Key (get from freepik.com/api)
• Playwright (pip install playwright && python -m playwright install chromium)

Installation

1. Clone the repository

git clone https://github.com/YOUR_USERNAME/freepik-spaces-mcp.git
cd freepik-spaces-mcp

2. Install dependencies

pip install -r requirements.txt
python -m playwright install chromium

3. Configure environment

cp .env.example .env
# Edit .env and add your Freepik API key:
# FREEPIK_API_KEY=your_key_here

4. Start CDP-enabled Chrome

The MCP server attaches to your Chrome browser via CDP (Chrome DevTools Protocol). This uses a separate profile so your normal Chrome is unaffected.

Windows:

"C:\Program Files\Google\Chrome\Application\chrome.exe" ^
  --remote-debugging-port=9222 ^
  --user-data-dir="./data/browser/cdp-profile" ^
  --remote-allow-origins=* --no-first-run ^
  https://www.freepik.com/pikaso/spaces

macOS/Linux:

google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="./data/browser/cdp-profile" \
  --remote-allow-origins=* --no-first-run \
  https://www.freepik.com/pikaso/spaces

Then log into Freepik in the new Chrome window (first time only — session persists).

5. Add to Claude Code

Create .mcp.json in your project directory:

{
  "mcpServers": {
    "freepik-spaces": {
      "command": "python",
      "args": ["-m", "freepik_spaces_mcp"],
      "cwd": "/path/to/freepik-spaces-mcp",
      "env": {
        "FREEPIK_API_KEY": "your_key_here"
      }
    }
  }
}

6. Verify

Open Claude Code in the project directory. The MCP server should auto-start. Test with:

"List all available Freepik tools"

29 MCP Tools

Session Management

Tool	Description
init_session	Connect to CDP Chrome
open_space	Navigate to a Freepik Space
session_status	Check connection state

Persistent Node Creation (Liveblocks)

Tool	Description
create_persistent_image_node	Image Generator (107+ models)
create_persistent_video_node	Video Generator (Seedance, Kling, Veo, etc.)
create_persistent_voice_node	Voice/Audio Generator (ElevenLabs)
create_persistent_text_node	Text/Prompt node
create_persistent_assistant_node	AI Assistant node

Connections

Tool	Description
connect_nodes	Create persistent visual wire between nodes
disconnect_nodes	Remove a connection
remove_node	Delete a node and its connections

Execution

Tool	Description
run_node	Execute via Freepik's native Run (auto-fallback for voice)
get_creation	Get output URL of a generated creation

Direct Generation (REST API)

Tool	Description
generate_image_direct	Quick image generation (no Space needed)
generate_video_direct	Image-to-video generation
generate_voiceover_direct	Text-to-speech (ElevenLabs)
generate_music_direct	Background music generation
generate_sfx_direct	Sound effects generation

Graph Operations

Tool	Description
get_graph	Full graph state (nodes + edges + viewport)
get_nodes / get_edges	Node/edge summaries
fit_view	Zoom to show all nodes
export_graph / import_graph	Backup/restore graph state

Pipelines

Tool	Description
build_pipeline	Text + Image Generator in one call
build_multi_angle_pipeline	Multi-angle with camera change

Example: UGC Influencer Pipeline

"Create a UGC podcast influencer pipeline:
1. Text node with a realistic webcam-style prompt
2. Front view image generator (nano-banana-2, 9:16)
3. Three-quarter angle connected to front (output→reference)
4. Selfie close-up connected to front (output→reference)
5. Video generator connected to front (output→reference)
6. Voice generator with a casual podcast script
7. Run the hero shot, then run all downstream nodes"

Claude will create 7 persistent nodes, connect them with visual wires, and run generations — all within your Freepik Space.

Supported AI Models (107+)

Image Generation

Nano Banana Pro/2, Flux 2/Pro/Kontext/Max, Seedream 4/5, Imagen 3/4/Ultra, Mystic, Z-Image, Ideogram, Recraft, GPT Image, Grok, Qwen, SAM-3

Video Generation

Seedance Pro/Lite/Fast, Kling 2.0-O1, Veo 2/3/3.1, Wan 2.2-2.7, Minimax, Luma Ray2, LTX2, PixVerse, Runway Gen4, Sora2

Audio

ElevenLabs TTS (v2.5/v3), Music Generation (Lyria), Sound Effects

Editing

Image Upscaler (Magnific), Skin Enhancer, Camera Angle Change, Style Transfer, Relight, Expand, Background Removal, Video Upscaler

Known Limitations

1. Voice Generator native Run — Freepik's execute_workflow API returns "Unsupported element type" for voice-generator nodes. The run_node MCP tool automatically falls back to REST API for voice generation.

2. New Space initialization — Creating a new Space via API (POST /pikaso/api/spaces) works, but the Liveblocks room may not initialize automatically. Workaround: open the new Space in Chrome first, then use the MCP tools.

3. Connections parentId — The Liveblocks connections collection ID ("0:69") is currently determined from the existing Space. Different Spaces may use different parent IDs.

4. Headless Chrome — Freepik's Cloudflare protection blocks headless Chromium. Use attach mode (connect to a real Chrome instance) instead.

5. Video thumbnails — After generating a video via native Run, the thumbnail may not appear immediately. A page reload shows it.

How It Works (Technical)

Liveblocks Integration

Freepik uses Liveblocks for real-time collaborative editing. This MCP server:

1. Injects a WebSocket constructor patch via Playwright's addInitScript (before page load)
2. Captures the Liveblocks WS connection (wss://api.liveblocks.io/v8?roomId=board-{uuid})
3. Sends Liveblocks operations (type:4 = create, type:3 = update, type:5 = delete) through the captured WS
4. Nodes created this way are persistent — they survive page reloads and are recognized by Freepik's server

workflowConnections

For character consistency across multi-angle pipelines, nodes must have workflowConnections set at creation time. This tells Freepik's backend which nodes are connected, enabling:

• Downstream cascade execution (run_downstream=true)
• Reference image passing (hero output → angle reference)
• Consistent character identity across all generated images

Vue Flow

Freepik Spaces uses Vue Flow (not React Flow). The graph state is accessible via:

document.querySelector("#app").__vue_app__
  .config.globalProperties.$vueFlowStorage
  .flows.get(spaceUUID)

Project Structure

freepik-spaces-mcp/
  freepik_spaces_mcp/
    __init__.py
    __main__.py          # Entry point: python -m freepik_spaces_mcp
    server.py            # FastMCP server with 29 tools
  app/
    browser/
      vue_flow_api.py    # Vue Flow + Liveblocks operations
      session.py         # Playwright CDP session manager
      selectors.py       # DOM selectors (Vue Flow verified)
    core/
      client.py          # Freepik REST API client (131 endpoints)
      token_tracker.py   # Credit quota tracking
    routers/             # FastAPI endpoints (optional HTTP layer)
    pipelines/           # Pre-built workflow templates
  scripts/
    start_chrome_with_cdp.bat   # Windows CDP launcher
    start_chrome_with_cdp.sh    # Linux/macOS CDP launcher
  .env.example           # Environment template
  .mcp.json              # Claude Code MCP config
  requirements.txt       # Python dependencies

Disclaimer

This project is provided "as is", without warranty of any kind, express or implied. By using this software, you acknowledge and agree that:

• This is an unofficial, community-built tool. It is not affiliated with, endorsed by, or sponsored by Freepik Company.
• You are solely responsible for your use of this software and for complying with Freepik's Terms of Service and API Terms.
• This software interacts with Freepik's services through browser automation and API calls. Use of this software may consume your Freepik API credits.
• The authors are not responsible for any costs, damages, account actions, or other consequences resulting from the use of this software.
• This software accesses Freepik's internal APIs and Liveblocks integration, which are not publicly documented and may change without notice, potentially breaking functionality.
• Do not share your API keys. Keep your .env file private and never commit it to version control.

Use at your own risk.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT License — see LICENSE file for details.