---
title: "iletiMerkezi MCP Server"
description: "Official Model Context Protocol server that connects the iletiMerkezi SMS API to Claude, Cursor, Cline, and other MCP-aware LLM clients."
slug: /en/docs/mcp
locale: en
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` is the official Model Context Protocol server that connects the iletiMerkezi SMS API to MCP-aware LLM clients such as Claude Code, Cursor, Codex CLI, Gemini CLI, VS Code (Cline), Claude Desktop, and other compatible clients. The LLM takes your natural-language request, picks the right tool call, and interprets the response. Sending SMS, pulling delivery reports, checking balance, and managing blacklists all happen inside a single conversation.

The server is fully open-source under MIT, written in TypeScript: [`iletimerkezi/iletimerkezi-mcp-server`](https://github.com/iletimerkezi/iletimerkezi-mcp-server).

## The 11 tools

| Tool | API endpoint | Purpose |
|---|---|---|
| `send_sms` | `POST /v1/send-sms/json` | Send SMS to one or many numbers (transactional 100/sec, bulk 50,000/request) |
| `cancel_order` | `POST /v1/cancel-order/json` | Cancel a future-scheduled order before dispatch |
| `get_report` | `POST /v1/get-report/json` | Single-order delivery report (summary + per-recipient) |
| `get_reports` | `POST /v1/get-reports/json` | Order summary list within a date range (max 10 days) |
| `get_balance` | `POST /v1/get-balance/json` | Account balance (TL + SMS credits) |
| `get_sender` | `POST /v1/get-sender/json` | Approved sender (header) list |
| `get_blacklist` | `POST /v1/get-blacklist/json` | Blocked numbers (paginated) |
| `add_blacklist` | `POST /v1/add-blacklist/json` | Block a number (idempotent) |
| `delete_blacklist` | `POST /v1/delete-blacklist/json` | Unblock a number |
| `iys_register` | `POST /v1/consent/create/json` | Register İYS consent records (batch, max 5000) |
| `iys_check` | `POST /v1/consent/show/json` | Look up İYS consent status for a recipient |

> **Built for Turkey.** `iys_register` lets you batch-create İYS consent records from the LLM conversation, `iys_check` returns the current consent status (ONAY / RET / source / date) for a single recipient, and `send_sms iys=1` triggers a real-time İYS lookup before dispatch. One of the first MCP servers to expose İYS as a first-class surface.

## Setup

### System requirements

| Requirement | Value |
|---|---|
| Package | [`@iletimerkezi/mcp-server`](https://www.npmjs.com/package/@iletimerkezi/mcp-server) (npm) |
| Minimum Node.js | **18.x** (LTS recommended: 20.x or 22.x) |
| Run mode | `npx -y @iletimerkezi/mcp-server`, no permanent install needed; npx attempts to use the latest version (an older one may be used if the local npx/pnpm cache is warm or you are offline) |
| Pinning a version (recommended) | `npx -y @iletimerkezi/mcp-server@1.0.0`, use it in production for deterministic behaviour |

Check the latest published version with `npm view @iletimerkezi/mcp-server version`.

Every MCP-aware client follows the same pattern: add an `iletimerkezi` server entry to a config file, pass credentials as environment variables, restart the client. Five clients share an identical JSON schema; Codex CLI uses a different format (TOML).

### Credentials (shared across clients)

Both values come from `panel.iletimerkezi.com` > **Settings > Security > API Access**. Don't compute the hash yourself, the panel issues a precomputed value. See [authentication](./api/authentication.md).

> **Important prerequisite:** The panel's **Settings > Security > Access Permissions > Allow API access** toggle must be ON. If it is off, every call returns `401`. The server's error message walks you through this exact toggle.

### Which client, which file

| Client | Config file | Format |
|---|---|---|
| **Claude Code** | command: `claude mcp add ...` or `.mcp.json` (project) / `~/.claude.json` (user) | JSON `mcpServers` |
| **Cursor** | `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project) | JSON `mcpServers` |
| **Gemini CLI** | `~/.gemini/settings.json` (global) or `.gemini/settings.json` (project) | 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** | command: `codex mcp add ...` or `~/.codex/config.toml` | TOML `[mcp_servers.X]` |

### Shared JSON config

Cursor, Gemini CLI, VS Code+Cline, Claude Desktop, and Claude Code (project-scope `.mcp.json`) all accept the same JSON shape. Add this block to the relevant file:

```json
{
  "mcpServers": {
    "iletimerkezi": {
      "command": "npx",
      "args": ["-y", "@iletimerkezi/mcp-server"],
      "env": {
        "ILETIMERKEZI_API_KEY": "your-api-key",
        "ILETIMERKEZI_API_HASH": "your-api-hash"
      }
    }
  }
}
```

Quit the client fully and reopen it. The 11 tools become available.

### Claude Code, single command

Install at user scope (available across all projects):

```bash
claude mcp add iletimerkezi -s user \
  -e ILETIMERKEZI_API_KEY=your-api-key \
  -e ILETIMERKEZI_API_HASH=your-api-hash \
  -- npx -y @iletimerkezi/mcp-server
```

Close the current Claude Code session and start a new one. Tools appear under the `mcp__iletimerkezi__*` prefix. To remove: `claude mcp remove iletimerkezi -s user`.

For teams, drop a project-scope `.mcp.json` (the shared JSON shape above) at the repo root; each developer sets the env vars in their shell profile so credentials never land in the repo.

### Codex CLI, TOML format

Via the CLI:

```bash
codex mcp add iletimerkezi \
  --env ILETIMERKEZI_API_KEY=your-api-key \
  --env ILETIMERKEZI_API_HASH=your-api-hash \
  -- npx -y @iletimerkezi/mcp-server
```

Or edit `~/.codex/config.toml` directly:

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

[mcp_servers.iletimerkezi.env]
ILETIMERKEZI_API_KEY = "your-api-key"
ILETIMERKEZI_API_HASH = "your-api-hash"
```

### Verifying

On first use, prefer two account-safe tools because they don't burn credits:

- `get_balance`, reads account balance
- `get_sender`, lists approved sender IDs

If both succeed, the install is correct.

## Single source of truth

`@iletimerkezi/mcp-server` does not author its own tool schemas. Tool definitions are pulled at runtime from [`/api/manifest.json`](/api/manifest.json), which is generated from the canonical iletiMerkezi endpoint documentation. A documentation update propagates to every running MCP client within 24 hours, no `npm update` required.

This setup means:

- The manifest is the **canonical source** for both the docs and the MCP tools, minimizing drift between the live API and what the LLM sees; a docs update propagates automatically to MCP.
- If iletimerkezi.com is unreachable, the server keeps working using a **build-time fallback** baked into the npm package at publish time.
- New endpoints become tools as soon as the docs are published.

## Example prompts

A single English sentence becomes one tool call behind the scenes:

- "Show me my balance." > `get_balance`
- "Send 'Your appointment is tomorrow at 2pm' to 905XXXXXXXXX." > `send_sms` (sender, iys, full envelope handled automatically)
- "Pull the delivery report for order 312988299." > `get_report`
- "List the SMS I sent last week." > `get_reports` (date range inferred automatically)
- "Cancel the order I scheduled for tomorrow at 9am." > `cancel_order`
- "Register these form responses in İYS as ONAY: ..." > `iys_register` (up to 5000 in one call)
- "What's the İYS consent status for this 0533 number?" > `iys_check`
- "Block this number." > `add_blacklist`
- "List my approved sender IDs." > `get_sender`

## Security

- The API Key + Hash carry full account permissions; if leaked, a single API call can drain the balance.
- Never commit credentials to source code or output files; the MCP client config stays on your local machine.
- The server does not retain credentials in memory; it reads them from env on every call.
- For production integrations, enable IP restriction and rotate keys monthly.

## Help and contributing

- Bug reports: [GitHub Issues](https://github.com/iletimerkezi/iletimerkezi-mcp-server/issues)
- API documentation: [API overview](./api/overview.md)
- Error codes: [Error codes table](./api/error-codes.md)
- Support: `destek@emarka.com.tr`