iletimerkezi-mcp-server

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.