iletiMerkezi MCP Server

iletiMerkezi MCP Server

Servidor do Model Context Protocol para a API SMS do iletiMerkezi. Permite que clientes LLM compatíveis com MCP (Claude Code, Cursor, Codex CLI, Gemini CLI, VS Code+Cline, Claude Desktop, …) enviem SMS, consultem relatórios de entrega e gerenciem remetentes / listas negras por meio de chamadas de ferramentas.

O iletiMerkezi é uma plataforma turca de SMS em massa / OTP / A2P licenciada pela BTK. As formas das ferramentas (esquemas de entrada, descrições, links de documentação) são derivadas de um manifesto de API canônico, construído a partir da documentação oficial dos endpoints, de modo que este servidor permanece em sincronia com a API ao vivo por design.

Ferramentas

Ferramenta	Endpoint da API	Notas
send_sms	POST /v1/send-sms/json	Envia SMS para um ou vários números (transacional 100/seg, em massa 50.000/requisição)
cancel_order	POST /v1/cancel-order/json	Cancela um pedido agendado para o futuro antes do envio
get_report	POST /v1/get-report/json	Relatório de entrega de um único pedido (resumo + por destinatário)
get_reports	POST /v1/get-reports/json	Lista de resumo de pedidos em um intervalo de datas (máx. 10 dias)
get_balance	POST /v1/get-balance/json	Saldo da conta (TL + créditos de SMS)
get_sender	POST /v1/get-sender/json	Lista de remetentes aprovados (cabeçalho)
get_blacklist	POST /v1/get-blacklist/json	Números bloqueados (paginado)
add_blacklist	POST /v1/add-blacklist/json	Bloqueia um número (idempotente)
delete_blacklist	POST /v1/delete-blacklist/json	Desbloqueia um número
iys_register	POST /v1/consent/create/json	Registra registros de consentimento İYS (em lote, máx. 5000)
iys_check	POST /v1/consent/show/json	Consulta o status de consentimento İYS para um destinatário

Instalação

Cinco clientes compartilham o mesmo esquema JSON mcpServers; Claude Code e Codex CLI também expõem um comando CLI de uma linha. Escolha seu cliente abaixo.

Cliente → arquivo de configuração

Cliente	Arquivo de configuração	Formato
Claude Code	claude mcp add ... (CLI) · .mcp.json (projeto) · ~/.claude.json (usuário)	JSON mcpServers
Cursor	~/.cursor/mcp.json (global) · .cursor/mcp.json (projeto)	JSON mcpServers
Gemini CLI	~/.gemini/settings.json (global) · .gemini/settings.json (projeto)	JSON mcpServers
VS Code + Cline	cline_mcp_settings.json (Cline → MCP Servers → Configurar)	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]

Configuração JSON compartilhada (Claude Code, Cursor, Gemini CLI, VS Code+Cline, Claude Desktop)

Adicione este bloco ao arquivo de configuração relevante:

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

Feche e reabra completamente o cliente. As 11 ferramentas aparecem sob o servidor iletimerkezi.

Claude Code — comando único

Escopo do usuário (disponível em todos os projetos):

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

Feche a sessão atual do Claude Code e inicie uma nova. As ferramentas aparecem como mcp__iletimerkezi__*. Remova com claude mcp remove iletimerkezi -s user.

Codex CLI — formato TOML

Via CLI:

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

Ou edite ~/.codex/config.toml diretamente:

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

Verificação

No primeiro uso, tente get_balance e get_sender — ambos são somente leitura e não consomem créditos.

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

Esses clientes exigem MCP remoto (endpoints HTTPS) e não executam comandos locais npx. Este servidor opera apenas no modo stdio (local) hoje. O suporte a hospedagem está no roadmap.

Credenciais

Ambos os valores vêm de panel.iletimerkezi.com → Configurações → Segurança → Acesso à API. Copie-os como estão — não faça hash você mesmo; o painel emite um hash pré-computado.

Você também precisa habilitar Permitir acesso à API em Configurações → Segurança → Permissões de acesso, caso contrário, toda chamada retorna 401. Este é o erro de integração mais comum; a mensagem de erro 401 do servidor aponta para essa opção.

Para o contrato completo de autenticação, veja https://www.iletimerkezi.com/docs/api/authentication.

Como os formatos das ferramentas se mantêm atualizados

Na inicialização, o servidor tenta, nesta ordem:

1. Cache local em ~/.cache/iletimerkezi-mcp/manifest.json, válido por 24 horas.
2. Busca ao vivo de https://www.iletimerkezi.com/api/manifest.json (timeout de 5s). Em caso de sucesso, atualiza o cache atomicamente.
3. Fallback em tempo de build (dist/manifest.fallback.json) incluído no pacote npm — o snapshot do manifesto no momento de npm publish.

Isso significa que novos endpoints ou alterações de esquema publicados no manifesto se propagam para clientes em execução em até 24 horas, sem necessidade de npm update. Não há nenhum esquema de ferramenta escrito manualmente em qualquer lugar deste repositório — a documentação da API é a única fonte de verdade.

Você pode substituir a URL do manifesto com ILETIMERKEZI_MANIFEST_URL para ambientes de staging / preview.

Desenvolvimento local

npm install
npm run build
npm test

Teste o servidor contra a API ao vivo com credenciais no seu shell:

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

Isso fala MCP via stdio. Use um cliente MCP para interagir ou envie um handshake JSON-RPC manualmente para depuração.

Referência

• Guia de configuração MCP: https://www.iletimerkezi.com/docs/mcp (TR) · /en/docs/mcp (EN)
• Visão geral: https://www.iletimerkezi.com/docs/api/overview
• Autenticação: https://www.iletimerkezi.com/docs/api/authentication
• Códigos de erro: https://www.iletimerkezi.com/docs/api/error-codes
• Manifesto (legível por máquina): https://www.iletimerkezi.com/api/manifest.json
• Notas de versão: CHANGELOG.md

Licença

MIT — veja LICENSE.