Freepik

🚀 Freepik MCP Server

This is an MCP server implementation that interacts with Freepik's API, providing the ability to access stock photos and Mystic AI image generation features.

🚀 Quick Start

The Freepik MCP Server allows you to interact with Freepik's API to access stock photos and use Mystic AI for image generation. Follow the steps below to get started.

✨ Features

• Search for Freepik resources (photos, vectors, PSDs).
• Get detailed information about resources.
• Download resources.
• Generate images using Mystic AI.
• Check the status of image generation tasks.

📦 Installation

Prerequisites

• Node.js 18 or higher.
• Freepik API key (see API Setup Guide).

Steps

# Create a new MCP server directory
mkdir mcp-servers
cd mcp-servers

# Clone the repository
git clone https://github.com/MCERQUA/freepik-mcp.git
cd freepik-mcp

# Install dependencies
npm install

# Build the server
npm run build

📚 Documentation

Configuration

1. First, obtain your Freepik API key as described in API_SETUP.md.
2. Add the server to your MCP settings file:

{
  "mcpServers": {
    "freepik": {
      "command": "node",
      "args": ["path/to/freepik-mcp/build/index.js"],
      "env": {
        "FREEPIK_API_KEY": "your-api-key-here"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Available Tools

search_resources

Search for Freepik resources using various filters:

{
  term?: string;          // Search term
  limit?: number;         // Number of results per page
  order?: 'relevance' | 'recent';
  filters?: {
    orientation?: {
      landscape?: boolean;
      portrait?: boolean;
      square?: boolean;
      panoramic?: boolean;
    };
    content_type?: {
      photo?: boolean;
      psd?: boolean;
      vector?: boolean;
    };
    license?: {
      freemium?: boolean;
      premium?: boolean;
    };
  };
}

get_resource

Get detailed information about a specific resource:

{
  id: number;  // ID of the resource to get details for
}

download_resource

Get the download URL for a specific resource:

{
  id: number;  // ID of the resource to download
}

generate_image

Generate an image using Freepik Mystic AI:

{
  prompt: string;         // Text description of the image
  resolution?: '2k' | '4k';
  aspect_ratio?: 'square_1_1' | 'classic_4_3' | 'traditional_3_4' | 
                 'widescreen_16_9' | 'social_story_9_16';
  realism?: boolean;      // Enable realistic style
  engine?: 'automatic' | 'magnific_illusio' | 'magnific_sharpy' | 'magnific_sparkle';
  creative_detailing?: number;  // 0-100
}

check_status

Check the status of a Mystic image generation task:

{
  task_id: string;  // ID of the generation task to check
}

Development

# Install dependencies
npm install

# Build the server
npm run build

# Run in development mode
npm run dev

Error Handling

This server implementation includes comprehensive error handling:

• Log detailed information about API errors.
• Use Zod schema for input validation.
• Provide correct error responses with context.
• Be aware of rate limits.

Contribution

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m "your-message").
4. Push to the branch (git push origin feature/amazing-feature).
5. Open a pull request.

More Information

For more information on how to use this project, see Project Documentation.