README.mdā¢4.59 kB
# 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](https://docs.astral.sh/uv/getting-started/installation/))
- **Freepik API Key** ([get yours here](https://freepik.com/api))
## š Installation
### 1. Clone and navigate
```bash
git clone <REPOSITORY_URL>
cd freepik-mcp
```
### 2. Install using Makefile
```bash
# Install dependencies
make install
# Verify installation
make version
```
### 3. Configure your API Key
```bash
echo "FREEPIK_API_KEY=your_api_key_here" > .env
```
> š” **Get your API Key at:** [freepik.com/api](https://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.
```json
{
"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:**
```bash
pwd
# Copy the output and replace /FULL/PATH/TO/ in the config
```
2. **Replace with your API key:**
- Get it from [freepik.com/api](https://freepik.com/api)
- Replace `your_actual_api_key_here`
## šāāļø Quick Start
```bash
# 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:**
```bash
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](https://freepik.com/api)
## š Troubleshooting
**Common issues:**
1. **"Command not found"** ā Install `uv` dependency manager
2. **"Invalid API Key"** ā Check your key at [freepik.com/api](https://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? šØāØ**