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:

{
  "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):

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:

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:

[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:

1. Local cache at ~/.cache/iletimerkezi-mcp/manifest.json, valid for 24 hours.
2. Live fetch of https://www.iletimerkezi.com/api/manifest.json (5s timeout). On success, refreshes the cache atomically.
3. 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

npm install
npm run build
npm test

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

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.