Freepik MCP: Complete Guide (2026)

Freepikfreepik-company

Official1-Click ReadyRemote

Freepik integration for searching and downloading icons, managing design assets, and generating images via text-to-image with job tracking and polling.

ai mldesign4581

One-sentence definition

The Freepik MCP server is an official, local stdio server that wraps the Freepik API so an AI client can generate images with the Mystic model, search and download icons, manage design resources, and classify images — using a single FREEPIK_API_KEY.

It lives at github.com/freepik-company/freepik-mcp and is tracked on our /servers/freepik catalog page. It is a Python project built on FastMCP, and it runs as a subprocess that your client launches over stdio — there is no hosted endpoint to point at.

Signal from Freepik

Freepik has been shipping API surface aggressively, folding new image models into the same developer platform this MCP server calls. Their developer account frames the API as the place where new models land:

That is the strategic backdrop: Freepik wants developers on the API, and the MCP server is the drop-in bridge from an agent to it. The catch, which this guide keeps returning to, is that the MCP server exposes only a slice of that API — Mystic, not the full model zoo you see in the web app.

Why it exists

Before an MCP server, wiring an agent to Freepik meant writing your own function-calling glue: define tool schemas by hand, map them to Freepik’s REST endpoints, handle auth, and poll the asynchronous generation jobs yourself. Every team rebuilt the same adapter, and every client (Claude Desktop, Cursor, VS Code) needed its own copy.

The Freepik MCP collapses that into one server. It reads Freepik’s OpenAPI specification, turns the allowed endpoints into tools automatically, and adds a purpose-built Mystic tool that waits for the image to finish rendering before it returns. You install once and every MCP client gets the same capabilities. That is the whole point of the protocol, applied to a stock-and-generation platform.

Mental model: the named pieces

Four pieces do all the work:

• Freepik API — the REST service at api.freepik.com that actually searches assets and runs generations. Paid, credit-based, keyed.
• OpenAPI-to-tools loader — the server fetches Freepik’s OpenAPI spec (cached ~1 hour) and FastMCP.from_openapi() generates MCP tools from it, so tool definitions track the API rather than being hand-written.
• Route map filter — a small allowlist that exposes only icons, resources, the image classifier, and Mystic; every other route is excluded “for security and simplicity,” in the code’s words.
• Mystic sync tool — a hand-written wrapper, text_to_image_mystic_sync, that submits a generation and polls until it completes, so the agent gets a finished image instead of a job ID.

Agent client (Claude / Cursor / VS Code)
          |
          | MCP tool call over stdio
          v
   Freepik MCP server (FastMCP, local)
          |  1. load OpenAPI spec  -> generate tools
          |  2. route-map filter   -> icons/resources/classifier/mystic
          |  3. mystic sync tool   -> submit + poll until done
          v
     api.freepik.com  (FREEPIK_API_KEY, credits)
          |
          v
   Icons, resources, classification, or a finished Mystic image

Opinionated takeaway: the interesting engineering here is not the model — it is the route filter and the polling wrapper. They are what make a generic REST API safe and pleasant to hand to an autonomous agent.

The tool surface (what is actually exposed)

The server does not expose all of Freepik’s API. Its route configuration maps four groups of endpoints to tools and excludes everything else. Verified against the repository source:

Because tools are generated from the live OpenAPI spec, the exact tool names and parameters follow Freepik’s operation IDs and can shift as the API evolves. The one name that is stable and hand-defined is text_to_image_mystic_sync, the Mystic wrapper. On models: this server generates with Mystic, Freepik’s own text-to-image model — not Flux. Freepik’s platform runs Flux and other models too, but the route map only wires the Mystic path, so that is what you get from the MCP.

Install (verified, copy-paste)

There is no npx or uvx one-liner yet (that is an open feature request on the repo). You clone the repo, install with uv, add your key, and point your client at the local entry file. These steps are copied verbatim from the official README.

Prerequisites: Python 3.12+, the uv dependency manager, and a Freepik API key from freepik.com/api. Windows users must run this under WSL.

Clone and install:

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

# install dependencies
make install

# verify it installed
make version

Add your API key as a local environment file:

echo "FREEPIK_API_KEY=your_api_key_here" > .env

Then register the server with your client. For Claude Desktop or Cursor, add this to the client’s MCP config, replacing the path and the key (run pwd inside the cloned folder to get the absolute path):

{
  "mcpServers": {
    "freepik-fastmcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/FULL/PATH/TO/freepik-mcp",
        "main.py"
      ],
      "env": {
        "FREEPIK_API_KEY": "your_actual_api_key_here"
      }
    }
  }
}

Restart the client. For Claude Desktop, the config is claude_desktop_config.json (on macOS: ~/Library/Application Support/Claude/). For Cursor, it is ~/.cursor/mcp.json. For running MCP servers from the terminal-based agent, see our Claude Code client guide. The key is passed per client via the env block, so keep it out of any committed file.

Smallest end-to-end run

Once the server is registered and the client restarted, the tools appear at session start (clients lazy-load tools, so a restart is what makes them show up). A first prompt that exercises the whole path:

The agent calls text_to_image_mystic_sync with your prompt, the server submits the Mystic job and polls until it finishes (up to a 300-second timeout), and the finished image comes back in the conversation. It then calls the icon search tool for the book icons and can download them. Two capabilities, one prompt, no dashboard.

If nothing happens, the tool almost certainly did not register — check the client’s MCP log for a stderr line from uv, which is where a bad path or a missing key surfaces.

Deep dive

1) Tools are generated from OpenAPI, not hand-written

The server calls FastMCP.from_openapi() with Freepik’s specification, loaded once and cached for about an hour. That means the tool catalog is derived from the API contract rather than maintained by hand, so it stays closer to what the API actually offers.

Takeaway: this is a low-maintenance design, but it also means tool names and parameter shapes are Freepik’s to change. Do not hard-code assumptions about a specific tool name except the Mystic wrapper, which is explicitly defined in the server.

2) The Mystic tool is synchronous by construction

Image generation is asynchronous on Freepik’s side: you submit a job and it completes later. Naively exposed, an agent would get a job ID and have to remember to poll it — something models do unreliably. The server solves this with text_to_image_mystic_sync, which submits the generation and polls to completion (with a 300-second timeout) before returning. The agent experiences one call that yields a finished image.

Takeaway: this single design choice is why the server feels usable in chat. It is also the source of most latency — you are waiting on a real render inside one tool call.

3) The route filter is a deliberate security boundary

The route configuration exposes icons, resources, the classifier, and Mystic, then adds a catch-all rule that excludes every other endpoint. A comment in the source states the intent plainly: exclude the rest “for security and simplicity.” So the agent cannot reach account, billing, or other sensitive Freepik routes even though your key technically could.

Takeaway: this is the right default for handing an API to an autonomous model. If you fork the server to add a route, you are also widening the blast radius of the key — do it deliberately.

4) One key, local transport, dynamic auth per request

Auth is a single FREEPIK_API_KEY, read from the environment or the .env file, and the HTTP client attaches it per request. Transport is stdio only: the server runs mcp.run(transport="stdio"), so it is a local subprocess, not a remote URL. There is no OAuth and no hosted endpoint in this repository today.

Takeaway: treat the key like a production credential. Because it sits in a client config or a local .env, keep it out of source control and scope it to what you are comfortable an agent spending.

What I got wrong

1) I assumed “Freepik MCP” meant the whole model zoo. Freepik’s app advertises Flux, Mystic, and a long list of models. I expected the MCP to expose all of them. It does not — the route map wires exactly one generation path, Mystic. Reading the code, not the marketing, corrected this.

2) I expected a one-line install like most 2026 servers. Many MCP servers ship as npx or uvx packages. This one does not yet; you clone and run with uv, and you must supply an absolute path. The uvx request is open on the tracker, so this may change.

3) I treated the API key as free-tier by habit. The Freepik web app has generous free credits, so I assumed the API did too. The API is a separate paid, credit-based product; every Mystic call costs credits. Budget before you let an agent loop on generations.

Common mistakes

Drawn from the repository’s open issues and the install flow. Each has a root cause, not just a “don’t.”

• Server will not start in VS Code. Root cause: runtime or path. The --directory value must be the absolute path to the clone, and uv plus Python 3.12+ must be on the launch PATH. This is an open issue on the repo; confirm the command runs from your own shell first.
• All 4:5 generations fail. Root cause: a known bug — a stray apostrophe in the aspect_ratio enum value for the social 4:5 format. Until it is patched, avoid the 4:5 aspect ratio or pin to another ratio.
• Looking for an OAuth / no-key setup. Root cause: it does not exist yet. Account-based OAuth is an open feature request; today the only auth is the API key.
• Windows launch failures. Root cause: the README requires WSL on Windows. Native Windows shells are not a supported launch path.
• Tools do not appear after editing config. Root cause: clients load tools at session init. Restart the client; editing the JSON while it runs does nothing until reload.

Cost and performance

Two numbers shape real use: credits and latency.

• Credits. The Freepik API is paid and credit-based. The per-image cost depends on the model and settings and is not fixed, so check the Freepik API pricing as of when you read this. Designers on Reddit repeatedly report that Freepik credits drain faster than expected on high-resolution work — the same caution applies double when an agent can trigger generations in a loop.
• Latency. A Mystic call blocks until the render finishes, up to the 300-second polling timeout. Treat it as a slow, variable tool, not an instant one. Design prompts so the agent generates once with clear constraints rather than spraying variations.
• Context. Icon and resource searches can return large result sets. Ask for a small count and specific criteria so responses do not eat the model’s context window.

Official vs the many forks

Search “freepik mcp” and you will find several repositories. Only one is Freepik’s own. The rest are independent community wrappers with different scopes and licenses:

• freepik-company/freepik-mcp — the official server this guide covers. Python, FastMCP, Mystic + icons + resources + classifier.
• Community forks such as MCERQUA/freepik-mcp (a Node implementation focused on stock photos and Mystic), grafikogr/freepik-mcp-server (Flux-Dev generation), and geopopos/freepik_mcp (an upscaler wrapper). Useful, but unofficial and separately maintained.

One honesty note worth flagging: some third-party directory listings describe the official repo as MIT-licensed, but at the time of writing the repository ships no license file and GitHub reports no detected license. That matters if you plan to fork or redistribute it — verify the license state yourself before you rely on it. If you are comparing generation options broadly, our Nano Banana vs DALL·E vs Midjourney vs Flux comparison and the best MCP servers for design roundup put Freepik in context.

Who this is for

Verdict

Frequently asked questions

Glossary

All sources and links

Primary sources

• freepik-company/freepik-mcp — official repository, README, and route/server source.
• Freepik API — API key, models, and pricing.
• @freepikdevs on X — Freepik Developers, on models landing in the Freepik API.

Community and context

• Open issues on the repo (VS Code startup, 4:5 aspect-ratio bug, OAuth and uvx feature requests) — used for the common mistakes and FAQ.
• PulseMCP: Freepik — independent directory listing (note: its transport description differs from the repo source, which is stdio).
• Reddit designer sentiment on Freepik credit consumption — the recurring “credits drain fast” contrarian note.

Related on MCP.Directory

• Freepik MCP server page
• Nano Banana vs DALL·E vs Midjourney vs Flux (MCP)
• Best MCP servers for design (2026)
• Claude Code MCP client guide