iletiMerkezi MCP Server

iletiMerkezi MCP Server

Servidor del Protocolo de Contexto de Modelo (MCP) para la API SMS de iletiMerkezi. Permite a los clientes LLM compatibles con MCP (Claude Code, Cursor, Codex CLI, Gemini CLI, VS Code+Cline, Claude Desktop, …) enviar SMS, consultar informes de entrega y gestionar remitentes / listas negras mediante llamadas a herramientas.

iletiMerkezi es una plataforma turca de SMS masivo / OTP / A2P con licencia BTK. Las formas de las herramientas (esquemas de entrada, descripciones, enlaces de documentación) se derivan de un manifiesto de API canónico que se construye a partir de la documentación oficial de los endpoints, por lo que este servidor se mantiene sincronizado con la API en vivo por diseño.

Herramientas

Herramienta	Endpoint de API	Notas
send_sms	POST /v1/send-sms/json	Enviar SMS a uno o muchos números (transaccional 100/seg, masivo 50,000/solicitud)
cancel_order	POST /v1/cancel-order/json	Cancelar un pedido programado para el futuro antes del envío
get_report	POST /v1/get-report/json	Informe de entrega de un solo pedido (resumen + por destinatario)
get_reports	POST /v1/get-reports/json	Lista de resumen de pedidos dentro de un rango de fechas (máx. 10 días)
get_balance	POST /v1/get-balance/json	Saldo de cuenta (TL + créditos SMS)
get_sender	POST /v1/get-sender/json	Lista de remitentes (encabezado) aprobados
get_blacklist	POST /v1/get-blacklist/json	Números bloqueados (paginado)
add_blacklist	POST /v1/add-blacklist/json	Bloquear un número (idempotente)
delete_blacklist	POST /v1/delete-blacklist/json	Desbloquear un número
iys_register	POST /v1/consent/create/json	Registrar registros de consentimiento İYS (lote, máx. 5000)
iys_check	POST /v1/consent/show/json	Consultar el estado de consentimiento İYS para un destinatario

Instalación

Cinco clientes comparten el mismo esquema JSON mcpServers; Claude Code y Codex CLI también exponen un comando CLI de una línea. Elige tu cliente a continuación.

Cliente → archivo de configuración

Cliente	Archivo de configuración	Formato
Claude Code	claude mcp add ... (CLI) · .mcp.json (proyecto) · ~/.claude.json (usuario)	JSON mcpServers
Cursor	~/.cursor/mcp.json (global) · .cursor/mcp.json (proyecto)	JSON mcpServers
Gemini CLI	~/.gemini/settings.json (global) · .gemini/settings.json (proyecto)	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]

Configuración JSON compartida (Claude Code, Cursor, Gemini CLI, VS Code+Cline, Claude Desktop)

Añade este bloque al archivo de configuración correspondiente:

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

Cierra y reinicia el cliente por completo. Las 11 herramientas aparecen bajo el servidor iletimerkezi.

Claude Code — comando único

Ámbito de usuario (disponible en todos los proyectos):

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

Cierra la sesión actual de Claude Code y comienza una nueva. Las herramientas aparecen como mcp__iletimerkezi__*. Elimínalas con claude mcp remove iletimerkezi -s user.

Codex CLI — formato TOML

Mediante la CLI:

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

O edita ~/.codex/config.toml directamente:

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

Verificación

En el primer uso, prueba get_balance y get_sender — ambos son de solo lectura, ninguno consume créditos.

Clientes alojados (ChatGPT Apps, Gemini App, Claude Web Connectors)

Estos clientes requieren MCP remoto (endpoints HTTPS) y no ejecutan comandos npx locales. Este servidor se distribuye solo en modo stdio (local) por ahora. El soporte alojado está en la hoja de ruta.

Credenciales

Ambos valores provienen de panel.iletimerkezi.com → Configuración → Seguridad → Acceso a la API. Cópialos tal cual — no los hashes tú mismo; el panel emite un hash precalculado.

También debes habilitar Permitir acceso a la API en Configuración → Seguridad → Permisos de acceso, de lo contrario cada llamada devuelve 401. Este es el error más común al comenzar; el mensaje de error 401 del servidor apunta a este interruptor.

Para el contrato completo de autenticación, consulta https://www.iletimerkezi.com/docs/api/authentication.

Cómo se mantienen actualizadas las formas de las herramientas

Al iniciar, el servidor intenta, en orden:

1. Caché local en ~/.cache/iletimerkezi-mcp/manifest.json, válida por 24 horas.
2. Obtención en vivo de https://www.iletimerkezi.com/api/manifest.json (tiempo de espera de 5s). En caso de éxito, actualiza la caché atómicamente.
3. Respaldo en tiempo de compilación (dist/manifest.fallback.json) incluido con el paquete npm — la instantánea del manifiesto en el momento de npm publish.

Esto significa que los nuevos endpoints o cambios de esquema publicados en el manifiesto se propagan a los clientes en ejecución dentro de 24 horas, sin necesidad de npm update. No hay ningún esquema de herramienta escrito manualmente en este repositorio: la documentación de la API es la única fuente de verdad.

Puedes sobrescribir la URL del manifiesto con ILETIMERKEZI_MANIFEST_URL para entornos de prueba / vista previa.

Desarrollo local

npm install
npm run build
npm test

Prueba el servidor contra la API en vivo con credenciales en tu shell:

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

Esto habla MCP sobre stdio. Usa un cliente MCP para interactuar, o canaliza un handshake JSON-RPC manualmente para depurar.

Referencia

• Guía de configuración de MCP: https://www.iletimerkezi.com/docs/mcp (TR) · /en/docs/mcp (EN)
• Resumen: https://www.iletimerkezi.com/docs/api/overview
• Autenticación: https://www.iletimerkezi.com/docs/api/authentication
• Códigos de error: https://www.iletimerkezi.com/docs/api/error-codes
• Manifiesto (legible por máquina): https://www.iletimerkezi.com/api/manifest.json
• Notas de versión: CHANGELOG.md

Licencia

MIT — consulta LICENSE.