MCP Servers

A collection of Model Context Protocol servers, templates, tools and more.

F
Freepik Spaces Claude Code MCP
by @yaniznayu
GitHub Repo(1 stars)

Claude Code MCP server for Freepik Spaces - 29 tools for persistent nodes, visual wires, native Run, multi-angle UGC pipelines with 107+ AI models

Created 4/12/2026
Updated about 7 hours ago
README
View Source
Repository documentation and setup instructions

Freepik Spaces MCP Server

ko-fi

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.

Quick Setup
Installation guide for this server

Install Package (if required)

uvx freepik-spaces-claude-code-mcp

Cursor configuration (mcp.json)

{ "mcpServers": { "yaniznayu-freepik-spaces-claude-code-mcp": { "command": "uvx", "args": [ "freepik-spaces-claude-code-mcp" ] } } }