Freepik FastMCP Toolkit

🚀 MCP Server for seamless Freepik API integration

🎯 What is this?

A Model Context Protocol (MCP) server that connects your AI assistants (Claude, Cursor, etc.) directly with Freepik’s powerful APIs. Generate, search, and manage visual content without leaving your AI workflow.

🛠️ What tools are available?

• 🎨 Icon Search & Download - Find and download icons in multiple formats
• 📁 Resource Management - Access and manage multimedia content
• 🤖 AI Image Classification - Automatically classify and analyze images
• 🖼️ Image Generation - Create custom images using Mystic AI

📋 Prerequisites

Before you start, make sure you have:

• Python 3.12+ installed
• uv dependency manager (install here)
• Freepik API Key (get yours here)

🚀 Installation

1. Clone and navigate

git clone 
cd freepik-toolkit/fastmcp

2. Install using Makefile

# Install dependencies
make install

# Verify installation
make version

3. Configure your API Key

echo "FREEPIK_API_KEY=your_api_key_here" > .env

💡 Get your API Key at: freepik.com/api

⚙️ Configuration for AI Assistants

For Claude Desktop or Cursor on Linux

Add this to your config.json file:

⚠️ For Windows users: If you’re on Windows, you need to use WSL (Windows Subsystem for Linux) to run this MCP server.

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

🔧 Important Configuration Steps

1. Find your full path:

   pwd
   # Copy the output and replace /FULL/PATH/TO/ in the config
   

2. Replace with your API key:

   • Get it from freepik.com/api
   • Replace your_actual_api_key_here

🏃‍♂️ Quick Start

# Development mode (auto-reload)
make dev

# Production mode  
make run

# Check code quality
make lint

# Format code
make format

# Clean temporary files
make clean

# See all commands
make help

🤝 Contributing

We welcome contributions! Please follow these guidelines:

📝 Commit Convention

This project uses Conventional Commits. Format your commits as:

(): 

[optional body]

[optional footer(s)]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, etc.)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks

Examples:

feat(icons): add search filtering by category
fix(api): resolve authentication timeout issue