Freepik MCP

🚀 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 <REPOSITORY_URL>
cd freepik-mcp

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",
        "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:

<type>(<scope>): <description>

[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
docs(readme): update installation instructions
refactor(mystic): improve error handling logic

🔄 Contribution Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feat/amazing-feature
3. Commit using conventional format: git commit -m "feat: add amazing feature"
4. Push to your branch: git push origin feat/amazing-feature
5. Open a Pull Request

📚 Development Commands

🛡️ Security

• ⚠️ Never commit your API Key
• ✅ Use .env files for sensitive data
• ✅ The .env file is in .gitignore

📖 API Documentation

For detailed API information:

• Freepik API Documentation

🆘 Troubleshooting

Common issues:

1. "Command not found" → Install uv dependency manager
2. "Invalid API Key" → Check your key at freepik.com/api
3. "Path not found" → Verify the full path in your config
4. "Connection refused" → Make sure the server is running with make dev

Still having issues? Open an issue on GitHub with:

• Your OS and Python version
• Full error message
• Configuration file (without API key)

Ready to create amazing content with AI? 🎨✨