BytePlus Image MCP

MCP server untuk generate image via BytePlus ModelArk (keluarga model Dola-Seedream 5.0 dari ByteDance) — dirancang untuk kebutuhan logo, mockup UI/UX, dan ilustrasi dokumen/proposal. Mendukung text-to-image dan image-to-image (edit/restyle/fusion dengan gambar referensi).

✨ Fitur

• Auto-routing model cerdas — sebut purpose saja, model dipilih otomatis:

  • logo / mockup → Dola-Seedream-5.0-pro (teks multibahasa termasuk Bahasa Indonesia, presisi tinggi)

  • document → Dola-Seedream-5.0-lite (hemat, resolusi hingga 4K)

• Image-to-image — berikan gambar referensi (image_paths path lokal / image_urls) untuk edit, restyle, atau fusion beberapa gambar (1–14 referensi)

• Multi-gambar per request via Lite (mode set gambar konsisten, 1–15)

• Resolusi per model: Pro 1K/1.5K/2K • Lite 2K/3K/4K — kombinasi tidak valid ditolak dengan pesan solutif

• Seed reproducible untuk hasil konsisten

• Auto-download hasil ke folder lokal (ekstensi png/jpg terdeteksi otomatis)

• Error handling lengkap dengan solusi konkret (Bahasa Indonesia)

Related MCP server: Volcengine Image Generation MCP Server

📊 Model

*Catatan: Pro hanya mendukung 1 gambar per request. Batch multi-gambar hanya via Lite.

Kuota gratis akun baru BytePlus. Daftar di console.byteplus.com. Aktifkan model di ModelArk → Model activation → tab Media.

🚀 Install

Prasyarat

1. Akun BytePlus dengan API key (ModelArk → API keys)

2. Aktifkan model Dola-Seedream-5.0 di ModelArk → Model activation → tab Media

3. Python ≥ 3.10 dan uv (opsional tapi disarankan)

Cara 1: uvx langsung dari GitHub (tanpa install manual)

{
  "mcpServers": {
    "byteplus-image": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/alecslacker/byteplus-image-mcp", "byteplus-image-mcp"],
      "env": {
        "BYTEPLUS_API_KEY": "isi-api-key-anda"
      }
    }
  }
}

Cara 2: pip install dari GitHub

pip install git+https://github.com/alecslacker/byteplus-image-mcp

Lalu di config MCP client:

{
  "mcpServers": {
    "byteplus-image": {
      "command": "byteplus-image-mcp",
      "env": { "BYTEPLUS_API_KEY": "isi-api-key-anda" }
    }
  }
}

Cara 3: jalankan file langsung (lokal)

git clone https://github.com/alecslacker/byteplus-image-mcp
cd byteplus-image-mcp
pip install mcp httpx pydantic
BYTEPLUS_API_KEY=isi-api-key-anda python src/byteplus_image_mcp/server.py

⚙️ Environment Variables

🛠️ Tools

byteplus_generate_image

Contoh pemakaian:

"Buatkan logo Duta Corpora"
→ byteplus_generate_image({
     prompt: "minimalist geometric logo, letter D monogram, gold on navy, flat vector",
     purpose: "logo"
   })

"Ilustrasi cover proposal"
→ byteplus_generate_image({
     prompt: "abstract tech illustration, flowing data lines, blue gradient",
     purpose: "document"
   })

"4 varian ilustrasi konsisten untuk slide deck"
→ byteplus_generate_image({
     prompt: "isometric illustration set of Indonesian village scenes ...",
     model: "seedream-5-0-260128",
     size: "2K",
     count: 4
   })

"Edit logo yang sudah ada: ganti warna jadi emas"
→ byteplus_generate_image({
     prompt: "change the logo color to luxurious gold, keep the shape and layout unchanged",
     image_paths: ["C:/uploads/logo-klien.png"],   // gambar referensi
     purpose: "logo"
   })

"Fusion: model dari gambar 1 memegang produk dari gambar 2"
→ byteplus_generate_image({
     prompt: "the person in image 1 holding the product from image 2, keep background unchanged",
     image_paths: ["C:/uploads/model.jpg", "C:/uploads/produk.jpg"]
   })

🖼️ Mode Image-to-Image

Berikan gambar referensi, prompt berubah fungsi menjadi instruksi edit:

1. Upload gambar ke chat MCP client (mis. TRAE) — agent akan mengambil path file-nya

2. Agent memanggil tool dengan image_paths (lokal) atau image_urls (URL, mis. hasil generate sebelumnya yang masih valid 24 jam)

3. Aturan: maks 14 gambar referensi (jpg/png/webp/bmp/tiff/gif, ≤10MB per gambar); Lite: total referensi + hasil ≤ 15; Pro: hasil selalu 1 gambar

Use case: edit logo klien existing, restyle foto produk, mockup dari sketsa, konsistensi karakter antar-aset.

byteplus_list_models

Lihat daftar model + harga + resolusi + panduan pemilihan.

📁 Output

Gambar tersimpan di BYTEPLUS_IMAGE_OUTPUT_DIR dengan nama {timestamp}-{slug-prompt}-{index}.png|.jpg (ekstensi mengikuti format asli dari API). URL dari API valid 24 jam; file lokal permanen.

🔒 Keamanan

• API key hanya via environment variable — tidak pernah di-hardcode

• Jangan commit .env atau key ke repository

• Monitor pemakaian: console.byteplus.com → ModelArk → Usage

📄 Lisensi

MIT — lihat LICENSE.