Freepik MCP

🚀 원활한 Freepik API 통합을 위한 MCP 서버

🎯 이것은 무엇인가요?

AI 어시스턴트(Claude, Cursor 등)를 Freepik의 강력한 API와 직접 연결하는 MCP(Model Context Protocol) 서버입니다. AI 워크플로우를 벗어나지 않고도 시각적 콘텐츠를 생성, 검색 및 관리할 수 있습니다.

🛠️ 어떤 도구를 사용할 수 있나요?

• 🎨 아이콘 검색 및 다운로드 - 여러 형식의 아이콘을 검색하고 다운로드합니다.

• 📁 리소스 관리 - 멀티미디어 콘텐츠에 액세스하고 관리합니다.

• 🤖 AI 이미지 분류 - 이미지를 자동으로 분류하고 분석합니다.

• 🖼️ 이미지 생성 - Mystic AI를 사용하여 맞춤형 이미지를 생성합니다.

📋 사전 요구 사항

시작하기 전에 다음 사항이 준비되어 있는지 확인하세요:

• Python 3.12+ 설치됨

• uv 의존성 관리자 (여기서 설치)

• Freepik API 키 (여기서 발급)

🚀 설치

1. 복제 및 이동

git clone <REPOSITORY_URL>
cd freepik-mcp

2. Makefile을 사용하여 설치

# Install dependencies
make install

# Verify installation
make version

3. API 키 구성

echo "FREEPIK_API_KEY=your_api_key_here" > .env

💡 API 키 발급처: freepik.com/api

⚙️ AI 어시스턴트 구성

Linux의 Claude Desktop 또는 Cursor용

config.json 파일에 다음을 추가하세요:

⚠️ Windows 사용자 참고: Windows를 사용하는 경우, 이 MCP 서버를 실행하려면 WSL(Windows Subsystem for Linux)을 사용해야 합니다.

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

🔧 중요한 구성 단계

1. 전체 경로 찾기:

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

2. API 키로 교체:

   • freepik.com/api에서 키를 가져옵니다.

   • your_actual_api_key_here 부분을 교체하세요.

🏃♂️ 빠른 시작

# 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

🤝 기여하기

기여를 환영합니다! 다음 가이드라인을 따라주세요:

📝 커밋 컨벤션

이 프로젝트는 Conventional Commits를 사용합니다. 커밋 형식을 다음과 같이 작성하세요:

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

[optional body]

[optional footer(s)]

유형:

• feat: 새로운 기능

• fix: 버그 수정

• docs: 문서 변경

• style: 코드 스타일 변경 (포맷팅 등)

• refactor: 코드 리팩토링

• test: 테스트 추가 또는 업데이트

• chore: 유지 관리 작업

예시:

feat(icons): add search filtering by category
fix(api): resolve authentication timeout issue
docs(readme): update installation instructions
refactor(mystic): improve error handling logic

🔄 기여 워크플로우

1. Fork 저장소

2. 기능 브랜치 생성: git checkout -b feat/amazing-feature

3. 컨벤션에 따른 커밋: git commit -m "feat: add amazing feature"

4. 브랜치 푸시: git push origin feat/amazing-feature

5. Pull Request 열기

📚 개발 명령어

🛡️ 보안

• ⚠️ API 키를 절대 커밋하지 마세요

• ✅ 민감한 데이터에는 .env 파일을 사용하세요

• ✅ .env 파일은 .gitignore에 포함되어 있습니다

📖 API 문서

상세한 API 정보는 다음을 참조하세요:

• Freepik API 문서

🆘 문제 해결

일반적인 문제:

1. "Command not found" → uv 의존성 관리자를 설치하세요.

2. "Invalid API Key" → freepik.com/api에서 키를 확인하세요.

3. "Path not found" → 구성 파일의 전체 경로를 확인하세요.

4. "Connection refused" → make dev로 서버가 실행 중인지 확인하세요.

여전히 문제가 발생하나요? 다음 정보를 포함하여 GitHub에 이슈를 제기해주세요:

• OS 및 Python 버전

• 전체 오류 메시지

• 구성 파일 (API 키 제외)

AI로 멋진 콘텐츠를 만들 준비가 되셨나요? 🎨✨