freepik-mcp

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

Command	Description
make help	Show all available commands
make install	Install dependencies
make dev	Run in development mode
make run	Run in production mode
make lint	Check code quality
make format	Format code automatically
make clean	Clean temporary files
make version	Check FastMCP version

🛡️ 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? 🎨✨