iletiMerkezi MCP Server

Model Context Protocol server for the iletiMerkezi SMS API. Lets MCP-aware LLM clients (Claude Code, Cursor, Codex CLI, Gemini CLI, VS Code+Cline, Claude Desktop, …) send SMS, query delivery reports, and manage senders / blacklists through tool calls.

iletiMerkezi is a Turkish, BTK-licensed bulk SMS / OTP / A2P platform. Tool shapes (input schemas, descriptions, doc links) are derived from a canonical API manifest that is built from the official endpoint documentation, so this server stays in lock-step with the live API by design.

Tools

Tool	API endpoint	Notes
`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

Installation

Five clients share the same JSON mcpServers schema; Claude Code and Codex CLI also expose a one-line CLI command. Pick your client below.

Client → config file

Client	Config file	Format
Claude Code	`claude mcp add ...` (CLI) · `.mcp.json` (project) · `~/.claude.json` (user)	JSON `mcpServers`
Cursor	`~/.cursor/mcp.json` (global) · `.cursor/mcp.json` (project)	JSON `mcpServers`
Gemini CLI	`~/.gemini/settings.json` (global) · `.gemini/settings.json` (project)	JSON `mcpServers`
VS Code + Cline	`cline_mcp_settings.json` (Cline → MCP Servers → Configure)	JSON `mcpServers`
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)	JSON `mcpServers`
Codex CLI	`codex mcp add ...` (CLI) · `~/.codex/config.toml`	TOML `[mcp_servers.X]`

Shared JSON config (Claude Code, Cursor, Gemini CLI, VS Code+Cline, Claude Desktop)

Add this block to the relevant config file:

config.json

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

Fully quit and relaunch the client. The 11 tools appear under the iletimerkezi server.

Claude Code — single command

User-scope (available across all projects):

Terminal

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 as mcp__iletimerkezi__*. Remove with claude mcp remove iletimerkezi -s user.

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, try get_balance and get_sender — both are read-only, neither burns credits.

Hosted clients (ChatGPT Apps, Gemini App, Claude Web Connectors)

These clients require remote MCP (HTTPS endpoints) and don't spawn local npx commands. This server ships in stdio (local) mode only today. Hosted support is on the roadmap.

Credentials

Both values come from panel.iletimerkezi.com → Settings → Security → API Access. Copy them as-is — do not hash them yourself; the panel issues a precomputed hash.

You also need to enable Allow API access under Settings → Security → Access Permissions, otherwise every call returns 401. This is the most common onboarding pitfall; the server's 401 error message points back to this toggle.

For the full authentication contract see https://www.iletimerkezi.com/docs/api/authentication.

How tool shapes stay fresh

On boot the server tries, in order:

Local cache at ~/.cache/iletimerkezi-mcp/manifest.json, valid for 24 hours.
Live fetch of https://www.iletimerkezi.com/api/manifest.json (5s timeout). On success, refreshes the cache atomically.
Build-time fallback (dist/manifest.fallback.json) shipped with the npm package — the manifest snapshot at the moment of npm publish.

This means new endpoints or schema changes published to the manifest propagate to running clients within 24 hours, with no npm update required. There is no manually written tool schema anywhere in this repo — the API documentation is the single source of truth.

You can override the manifest URL with ILETIMERKEZI_MANIFEST_URL for staging / preview environments.

Local development

Terminal

npm install
npm run build
npm test

Smoke-test the server against the live API with credentials in your shell:

bash

ILETIMERKEZI_API_KEY=... ILETIMERKEZI_API_HASH=... node dist/index.js

This speaks MCP over stdio. Use an MCP client to interact, or pipe a JSON-RPC handshake manually for debugging.

Reference

MCP setup guide: https://www.iletimerkezi.com/docs/mcp (TR) · /en/docs/mcp (EN)
Overview: https://www.iletimerkezi.com/docs/api/overview
Authentication: https://www.iletimerkezi.com/docs/api/authentication
Error codes: https://www.iletimerkezi.com/docs/api/error-codes
Manifest (machine-readable): https://www.iletimerkezi.com/api/manifest.json
Release notes: CHANGELOG.md

License

MIT — see LICENSE.