---
title: "iletiMerkezi MCP Server"
description: "iletiMerkezi SMS API'sini Claude, Cursor ve Cline gibi MCP destekli LLM istemcilerine bağlayan resmi Model Context Protocol sunucusu."
slug: /docs/mcp
locale: tr
audience: developer
last_updated: 2026-05-05
related: [overview, authentication, send-sms, get-report]
alternates:
  tr: https://www.iletimerkezi.com/docs/mcp
  en: https://www.iletimerkezi.com/en/docs/mcp
---

# iletiMerkezi MCP Server

`@iletimerkezi/mcp-server`, Claude Code, Cursor, Codex CLI, Gemini CLI, VS Code (Cline) ve Claude Desktop gibi **Model Context Protocol** istemcilerine iletiMerkezi SMS API'sini bağlayan resmi sunucudur. LLM, doğal dil isteğinizi alır, ilgili tool çağrısını üretir ve yanıtı yorumlar; SMS gönderimi, teslimat raporu, bakiye ve kara liste yönetimi tek bir konuşmadan yürütülebilir.

Sunucu tamamen TypeScript, MIT lisanslı, açık kaynaktır: [`iletimerkezi/iletimerkezi-mcp-server`](https://github.com/iletimerkezi/iletimerkezi-mcp-server).

## Sunduğu 11 tool

| Tool | API endpoint | Ne işe yarar |
|---|---|---|
| `send_sms` | `POST /v1/send-sms/json` | Tek veya çoklu numaraya SMS gönderir (anlık 100/sn, toplu 50.000/istek) |
| `cancel_order` | `POST /v1/cancel-order/json` | İleri tarihli siparişi operatöre verilmeden iptal eder |
| `get_report` | `POST /v1/get-report/json` | Tek sipariş teslimat raporu (özet + alıcı bazında) |
| `get_reports` | `POST /v1/get-reports/json` | Tarih aralığında sipariş özet listesi (max 10 gün) |
| `get_balance` | `POST /v1/get-balance/json` | Hesap bakiyesi (TL + SMS kontörü) |
| `get_sender` | `POST /v1/get-sender/json` | Onaylı sender ID listesi |
| `get_blacklist` | `POST /v1/get-blacklist/json` | Engellenmiş numaralar (sayfalı) |
| `add_blacklist` | `POST /v1/add-blacklist/json` | Numara engelle (idempotent) |
| `delete_blacklist` | `POST /v1/delete-blacklist/json` | Engellemeyi kaldır |
| `iys_register` | `POST /v1/consent/create/json` | İYS izin kaydı (toplu, max 5000) |
| `iys_check` | `POST /v1/consent/show/json` | İYS izin durumu sorgulama (tekil) |

> **Türkiye odağında öncü.** `iys_register` ile İYS izin kayıtlarını LLM diyaloğunun içinden batch olarak oluşturabilir, `iys_check` ile tek alıcının güncel izin durumunu (ONAY / RET / kaynak / tarih) sorgulayabilir, `send_sms iys=1` çağrısında gönderim öncesi gerçek-zamanlı İYS doğrulamasını otomatik tetikleyebilirsiniz. İYS entegrasyonunu birinci sınıf MCP yüzeyi olarak sunan Türkiye'ye özgü ilk yaklaşımlardan biri.

## Kurulum

### Sistem gereksinimleri

| Gereksinim | Değer |
|---|---|
| Paket | [`@iletimerkezi/mcp-server`](https://www.npmjs.com/package/@iletimerkezi/mcp-server) (npm) |
| Minimum Node.js | **18.x** (LTS önerilir: 20.x veya 22.x) |
| Çalışma şekli | `npx -y @iletimerkezi/mcp-server`, kalıcı kurulum gerektirmez; npx en son sürümü çekmeye çalışır (yerel npx/pnpm cache veya offline durumda eski sürüm kullanılabilir) |
| Sürüm pinleme (önerilen) | `npx -y @iletimerkezi/mcp-server@1.0.0`, production'da deterministik davranış için kullanın |

`npm view @iletimerkezi/mcp-server version` ile en son sürümü kontrol edebilirsiniz.

Her MCP-uyumlu istemcide aynı mantık geçerli: bir config dosyasına `iletimerkezi` sunucu girdisi ekle, kimlik bilgilerini env vars olarak geç, istemciyi yeniden başlat. Beş istemci aynı JSON şemasını paylaşır; Codex CLI farklı bir format (TOML) kullanır.

### Kimlik bilgileri (her istemci için ortak)

İki değer de `panel.iletimerkezi.com` > **Ayarlar > Güvenlik > API Erişimi** altından kopyalanır. Hash'i kendiniz hesaplamayın; panel hazır verir. Detay: [authentication](./api/authentication.md).

> **Önemli ön koşul:** Panel'de **Ayarlar > Güvenlik > Erişim İzinleri > API kullanımına izin ver** seçeneği açık olmalı. Kapalıysa her çağrı `401` döner. Sunucunun hata mesajı bu adımı doğrudan size hatırlatır.

### Hangi istemci, hangi dosya

| İstemci | Config dosyası | Format |
|---|---|---|
| **Claude Code** | komut: `claude mcp add ...` veya `.mcp.json` (proje) / `~/.claude.json` (user) | JSON `mcpServers` |
| **Cursor** | `~/.cursor/mcp.json` (global) veya `.cursor/mcp.json` (proje) | JSON `mcpServers` |
| **Gemini CLI** | `~/.gemini/settings.json` (global) veya `.gemini/settings.json` (proje) | JSON `mcpServers` |
| **VS Code + Cline** | `cline_mcp_settings.json` (Cline UI > MCP Servers > Configure) | JSON `mcpServers` |
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) | JSON `mcpServers` |
| **Codex CLI** | komut: `codex mcp add ...` veya `~/.codex/config.toml` | TOML `[mcp_servers.X]` |

### Ortak JSON konfigürasyonu

Cursor, Gemini CLI, VS Code+Cline, Claude Desktop ve Claude Code (proje-scope `.mcp.json`) için aynı JSON şeması geçerlidir. İlgili dosyaya aşağıdaki bloğu ekleyin:

```json
{
  "mcpServers": {
    "iletimerkezi": {
      "command": "npx",
      "args": ["-y", "@iletimerkezi/mcp-server"],
      "env": {
        "ILETIMERKEZI_API_KEY": "API_ANAHTARINIZ",
        "ILETIMERKEZI_API_HASH": "HASH_DEGERINIZ"
      }
    }
  }
}
```

İstemciyi tam quit ile kapatıp yeniden açın. 11 tool kullanılabilir hale gelir.

### Claude Code, tek komut

Komutla user-scope (tüm projelerde geçerli) kurulum:

```bash
claude mcp add iletimerkezi -s user \
  -e ILETIMERKEZI_API_KEY=API_ANAHTARINIZ \
  -e ILETIMERKEZI_API_HASH=HASH_DEGERINIZ \
  -- npx -y @iletimerkezi/mcp-server
```

Mevcut Claude Code oturumunu kapat, yenisini aç. Tools `mcp__iletimerkezi__*` ön ekiyle görünür. Kaldırma: `claude mcp remove iletimerkezi -s user`.

Ekipler için proje-scope `.mcp.json` (yukarıdaki ortak JSON şeması) repo köküne eklenir; her geliştirici env değişkenlerini kendi shell profilinde tanımlar, credential repo'ya commit edilmez.

### Codex CLI, TOML formatı

Komutla:

```bash
codex mcp add iletimerkezi \
  --env ILETIMERKEZI_API_KEY=API_ANAHTARINIZ \
  --env ILETIMERKEZI_API_HASH=HASH_DEGERINIZ \
  -- npx -y @iletimerkezi/mcp-server
```

Veya `~/.codex/config.toml` dosyasını manuel düzenle:

```toml
[mcp_servers.iletimerkezi]
command = "npx"
args = ["-y", "@iletimerkezi/mcp-server"]

[mcp_servers.iletimerkezi.env]
ILETIMERKEZI_API_KEY = "API_ANAHTARINIZ"
ILETIMERKEZI_API_HASH = "HASH_DEGERINIZ"
```

### Doğrulama

İlk denemede hesap-güvenli iki tool tercih edin, kontör harcamazlar:

- `get_balance`, hesap bakiyesini okur
- `get_sender`, onaylı başlıkları listeler

İkisi de başarılı yanıt veriyorsa kurulum doğru.

## Tek kaynak prensibi

`@iletimerkezi/mcp-server` kendi içinde tool şeması tanımlamaz. Tool tanımları çalışma anında [`/api/manifest.json`](/api/manifest.json) üzerinden çekilir. Manifest, iletiMerkezi'nin resmi endpoint dokümantasyonundan üretilir; yani belgelerdeki bir güncelleme 24 saat içinde tüm MCP istemcilerinde görünür hale gelir, `npm update` gerekmez.

Bu yapı:

- Manifest, hem dokümanların hem de MCP tool'larının **tek kanonik kaynağıdır**; aralarındaki drift en aza indirilir, dokümanlardaki bir güncelleme MCP tarafına otomatik yansır.
- iletimerkezi.com erişilemese bile sunucu, `npm publish` anında pakete gömülen **build-time fallback** ile çalışmaya devam eder.
- Yeni endpoint eklendiğinde, dokümantasyon yayınlanır yayınlanmaz LLM'ler tool olarak görür.

## Örnek konuşmalar

LLM'e söyleyeceğiniz cümle, sunucunun arkasında tek bir tool çağrısına dönüşür:

- "Bakiyemi göster." > `get_balance`
- "905XXXXXXXXX numarasına 'Randevunuz yarın 14:00' yaz." > `send_sms` (sender, iys, tüm zarf otomatik)
- "Şu sipariş numarasının teslimat raporunu çıkar: 312988299." > `get_report`
- "Son hafta gönderdiğim SMS'leri listele." > `get_reports` (tarih aralığı otomatik çıkarılır)
- "Yarın 09:00'a planladığım siparişi iptal et." > `cancel_order`
- "Bu form yanıtlarını İYS'ye ONAY olarak ekle: ..." > `iys_register` (5000'e kadar toplu)
- "0533 ile başlayan bu numaranın İYS izin durumu ne?" > `iys_check`
- "0532'li numarayı kara listeye ekle." > `add_blacklist`
- "Onaylı başlıklarımı listele." > `get_sender`

## Güvenlik

- API Anahtarı + Hash hesabınıza tam yetkiyle bağlıdır; sızdırılırsa tek çağrıyla bakiye harcanabilir.
- Anahtarları kaynak kodunda veya çıktı dosyalarında bulundurmayın; MCP istemcisinin config dosyası lokal makinenizde kalır.
- Sunucu, kimlik bilgilerini bellekte saklamaz; her çağrıda env'den okur.
- Üretim entegrasyonlarında IP kısıtlaması ve aylık anahtar rotasyonu önerilir.

## Yardım ve katkı

- Sorun bildirimi: [GitHub Issues](https://github.com/iletimerkezi/iletimerkezi-mcp-server/issues)
- API dokümantasyonu: [API Genel Bakış](./api/overview.md)
- Hata kodları: [Error Codes](./api/error-codes.md)
- Destek: `destek@emarka.com.tr`