Skip to main content
Glama
README.md
# 🛒 trendyol-mcp

Trendyol **Satıcı (Seller) API** için MCP (Model Context Protocol) sunucusu: ürün kataloğu, siparişler, iade/talepler, finans (settlement / diğer finansal işlemler / kargo faturası), müşteri faturaları, müşteri soruları (Q&A) ve webhook yönetimi — toplam 52 araç.

[cemre-2187/trendyol-api](https://github.com/cemre-2187/trendyol-api) paketinin bağımlılıksız portudur: HTTP çağrıları için ek kütüphane yerine Node'un yerleşik `fetch`'i kullanılır ve tüm uçlar güncel `https://apigw.trendyol.com/integration` tabanına taşınmıştır.

> ⚠️ Bu sunucu **canlı satıcı hesabınıza** bağlanır. Yazma araçları (ürün oluşturma/güncelleme, fiyat-stok, iade onaylama, fatura gönderme) gerçek veriyi değiştirir. Önce salt okunur araçlarla başlayın.

## Kurulum

Node.js 20.12+ gerekir.

```bash
git clone https://github.com/bevren/trendyol-market-mcp.git
cd trendyol-market-mcp
npm install
```

### Kimlik Bilgileri

Değerleri **Satıcı Paneli > Hesap Bilgileri > Entegrasyon Bilgileri** sayfasından alın.

```bash
Copy-Item .env.example .env   # sonra değerleri doldurun (.env git tarafından yok sayılır)
npm start
```

> ⚠️ `.env` dosyasını PowerShell ile sıfırdan **oluşturmayın**. `Set-Content -Encoding utf8` dosya başına BOM ekler; Node'un `--env-file` ayrıştırıcısı BOM'u temizlemediği için **dosyadaki ilk değişken sessizce yüklenmez**. `.env.example` dosyasını `Copy-Item` ile kopyalayın.

Alternatif olarak kimlik bilgileri çalışma anında `trendyol_configure` aracıyla da verilebilir.

| Değişken | Açıklama |
| --- | --- |
| `TRENDYOL_SELLER_ID` | Satıcı (supplier) ID |
| `TRENDYOL_API_KEY` | API anahtarı |
| `TRENDYOL_API_SECRET` | API gizli anahtarı |
| `TRENDYOL_STAGE_MODE` | `1`/`true`: tüm çağrılar `stageapigw.trendyol.com`'a gider (aşağıdaki nota bakın) |

### Claude Code

```bash
claude mcp add trendyol -- npx tsx <bu-deponun-yolu>/src/index.ts
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "trendyol": {
      "command": "npx",
      "args": ["tsx", "<bu-deponun-yolu>/src/index.ts"],
      "env": {
        "TRENDYOL_SELLER_ID": "...",
        "TRENDYOL_API_KEY": "...",
        "TRENDYOL_API_SECRET": "..."
      }
    }
  }
}
```

## Araçlar

| Grup | Araçlar |
| --- | --- |
| **Oturum** | `trendyol_configure`, `trendyol_session_info` |
| **Marka & Kategori** | `trendyol_get_brands`, `trendyol_get_brand_by_name`, `trendyol_create_brand`, `trendyol_get_category_tree`, `trendyol_get_category_attributes`, `trendyol_get_category_attribute_values` |
| **Ürün oluşturma/güncelleme** | `trendyol_create_products`, `trendyol_update_unapproved_products`, `trendyol_update_approved_product_content`, `trendyol_update_approved_product_variants`, `trendyol_update_product_delivery_info`, `trendyol_update_price_and_inventory` |
| **Ürün yaşam döngüsü** | `trendyol_archive_products`, `trendyol_unlock_products`, `trendyol_delete_products`, `trendyol_get_batch_request_result` |
| **Ürün sorgulama** | `trendyol_get_products`, `trendyol_filter_approved_products`, `trendyol_filter_unapproved_products`, `trendyol_filter_approved_products_inventory_and_price`, `trendyol_get_product_status`, `trendyol_get_buybox_info`, `trendyol_get_product_update_audits` |
| **Video** | `trendyol_create_video`, `trendyol_get_videos` |
| **Sipariş & Adres** | `trendyol_get_orders`, `trendyol_get_supplier_addresses` |
| **İade / Talep** | `trendyol_get_claims`, `trendyol_create_claim`, `trendyol_approve_claim_items`, `trendyol_create_claim_issue`, `trendyol_get_claim_issue_reasons`, `trendyol_get_claim_audits` |
| **Finans** | `trendyol_get_settlements`, `trendyol_get_other_financials`, `trendyol_get_cargo_invoice_items` |
| **Müşteri faturaları** | `trendyol_send_invoice_link`, `trendyol_delete_invoice_link`, `trendyol_send_invoice_file` |
| **Müşteri soruları** | `trendyol_get_questions`, `trendyol_get_question_by_id`, `trendyol_create_answer` |
| **Webhook** | `trendyol_register_webhook`, `trendyol_get_webhooks`, `trendyol_delete_webhook` |
| **Referans veri** | `trendyol_get_reference_data` (işlem türleri, iade nedenleri, kargo firmaları, menşei kodları, soru durumları, video içerik türleri…) |
| **Test (yalnızca stage)** | `trendyol_create_test_order`, `trendyol_update_test_order_status`, `trendyol_update_test_claim_to_waiting_in_action`, `trendyol_create_test_question` |

## Testler

```bash
npm run smoke   # MCP el sıkışması + araç listesi + şema testleri (ağ gerektirmez)
```

Smoke test sunucuyu doğrudan spawn ettiği için `.env` yüklenmez; tüm çağrılar kimlik bilgisi kapısında durur ve canlı API'ye istek gitmez.

## Bilinen Notlar

- **Stage ortamı panel kimlik bilgileriyle çalışmıyor** (16 Tem 2026'da doğrulandı): `stageapigw.trendyol.com`, panel anahtarlarını Cloudflare seviyesinde **403** ile reddeder — istek Trendyol'a hiç ulaşmaz. Aynı kimlikle prod 200 döner. Yani `TRENDYOL_STAGE_MODE=1` bir güvenlik ağı **değildir**: canlı veriyi korumaz, yalnızca her çağrıyı 403'e düşürür. Stage, Trendyol entegrasyon ekibinden talep edilen **ayrı test kimlikleri** ister; bu kimlikler olmadan `test_*` araçları kullanılamaz.
- **Finans uçları en fazla 15 günlük aralık kabul eder.** İstemci, verilen aralığı otomatik olarak 15 günlük pencerelere böler ve tüm sayfaları birleştirir. `transactionType` (tekil) veya `transactionTypes` (çoğul) zorunludur. Kayıtlar sipariş **teslim edildikten sonra** oluşur.
- **Müşteri soruları için 2 haftalık aralık sınırı sessizdir:** Trendyol aşımda hata vermez, `endDate`'i sessizce `startDate + 2 hafta` yapar. Bu yüzden araç uzun aralığı baştan reddeder.
- `invoiceNumber` biçimi 4 Ağustos 2023'ten beri **[3 alfanümerik][13 rakam] = 16 hane**'dir (Trendyol dokümanındaki `TY4874324` örneği bu kurala uymuyor; kural uygulanmıştır). Fatura bağlantısı yasal olarak 8 yıl erişilebilir kalmalıdır.
- `trendyol_get_products` eski (`/product/sellers/{id}/products`) ucu kullanır ve yeni `filter_*` araçlarıyla örtüşür; geriye dönük uyumluluk için tutulmaktadır.
- Doğrulama kuralları ağ çağrısından önce çalışır: `listPrice ≥ salePrice`, `fastDeliveryType` için `deliveryDuration=1`, barkod karakter kümesi, ≤8 görsel, ≤10 buybox barkodu, `page × size ≤ 10000`, video başlığı 3-50 karakter.

TDQS

A3.9/5.0

Scored across 52 tools

Disambiguation5/5

Each tool has a clearly distinct purpose, from product management to order handling, claims, questions, videos, webhooks, and financials. Even similar tools like filter_approved_products and get_products are differentiated by their scope and detail.

Naming Consistency4/5

Tools consistently use snake_case with a trendyol_ prefix and a verb_noun pattern. However, 'trendyol_session_info' lacks a verb (should be 'get_session_info' or 'show_session_info'), and some names like 'filter_approved_products_inventory_and_price' are overly long.

Tool Count3/5

With 52 tools, the count is high but reflects the breadth of the Trendyol seller API. Each tool serves a distinct purpose, though the sheer number may overwhelm agents and slightly exceeds typical coherence guidelines.

Completeness5/5

The tool set covers all major seller operations: CRUD for products, orders, claims, questions, videos, webhooks, and financials. It includes test tools and reference data retrieval, leaving no obvious gaps for standard platform tasks.

Maintenance

ActivityInactive
ResponsivenessNo recent community issues