opn-mcp

opn-mcp

Um servidor MCP para opn.onl — o encurtador de URLs open-source e auto-hospedável. Ele permite que assistentes de IA (Claude Desktop, Cursor, etc.) encurtem links, leiam análises, gerem códigos QR e gerenciem links em linguagem natural.

Funciona com o serviço hospedado ou com sua própria instância auto-hospedada.

Configuração

1. Obtenha uma chave de API

Na sua instância opn.onl, vá em Configurações → Chaves de API, crie uma chave e copie-a (ela começa com opn_ e é exibida apenas uma vez).

2. Adicione o servidor ao seu cliente MCP

Claude Desktop — edite claude_desktop_config.json (~/Library/Application Support/Claude/ no macOS, %APPDATA%\Claude\ no Windows):

{
  "mcpServers": {
    "opn": {
      "command": "npx",
      "args": ["-y", "opn-mcp"],
      "env": {
        "OPN_API_KEY": "opn_your_key_here"
      }
    }
  }
}

Reinicie seu cliente. Pronto — ele fala com a API hospedada (https://l.opn.onl) por padrão.

Prefere executar a partir do código-fonte? Troque o args pela versão do GitHub — mesma configuração: "args": ["-y", "github:ysalitrynskyi/opn-mcp"] (ele compila na instalação).

Instância auto-hospedada

Aponte OPN_BASE_URL para o host da API da sua própria instância:

{
  "mcpServers": {
    "opn": {
      "command": "npx",
      "args": ["-y", "opn-mcp"],
      "env": {
        "OPN_API_KEY": "opn_your_key_here",
        "OPN_BASE_URL": "https://l.your-domain.com"
      }
    }
  }
}

Configuração

Variável de ambiente	Obrigatório	Padrão	Descrição
OPN_API_KEY	✅	—	Sua chave de API (opn_…), de Configurações → Chaves de API
OPN_BASE_URL	—	https://l.opn.onl	URL base da API — defina isso para uma instância auto-hospedada

Ferramentas

Links

Ferramenta	Descrição
shorten_url	Crie um link curto — alias opcional, título, notas, agendamento (starts_at/expires_at), max_clicks, senha, queimar após leitura, pasta e tags
shorten_urls_bulk	Encurte várias URLs de uma vez, opcionalmente em uma pasta
list_links	Liste seus links (limite, deslocamento, busca, filtro por pasta ou tag)
update_link	Atualize destino, título, notas, agendamento, limite de cliques, pasta ou proteções; limpe campos com flags remove_*
delete_link	Exclua um link
clone_link	Duplique um link com um novo código curto
toggle_link_pin	Fixe ou desafixe um link
check_alias_available	Verifique se um alias personalizado está disponível antes de usá-lo

Análises

Ferramenta	Descrição
get_link_stats	Análises por link (cliques, visitantes únicos, geo, cidades, dispositivos, navegadores, SO, referenciadores); janela opcional days
get_dashboard_stats	Análises de toda a conta em todos os seus links

Utilitários de QR e URL

Ferramenta	Descrição
get_qr_code	Obtenha a imagem QR de um link — cor da marca opcional, logotipo central, PNG/SVG
check_url_health	Verifique se uma URL de destino está acessível antes de encurtar
build_utm_url	Adicione parâmetros de campanha UTM a uma URL
preview_url_metadata	Obtenha metadados Open Graph (título, descrição, imagem) para uma URL

Tags e pastas

Ferramenta	Descrição
list_tags / create_tag	Liste ou crie tags
add_tags_to_link / remove_tags_from_link	Anexe ou desanexe tags em um link
list_folders / create_folder	Liste ou crie pastas
move_links_to_folder	Mova links para uma pasta

Exemplos de prompts

• "Encurte https://example.com/very/long/url e chame-o de launch-2026"
• "Encurte estas cinco URLs em uma nova pasta chamada Q3 Campaign"
• "Quantos cliques o link 42 obteve nos últimos 30 dias, e de quais países?"
• "Me dê um código QR SVG com marca para o link 42"
• "Marque meus últimos 10 links como 'newsletter' e mostre minhas estatísticas do painel"
• "Crie um link UTM para https://example.com — fonte newsletter, meio email"

Desenvolvimento

npm install
npm run build      # tsc → dist/
npm test           # vitest
OPN_API_KEY=opn_… npm run dev   # run from source (stdio)

Publicação

Todos os três registros são de propriedade de ysalitrynskyi (usuário npm, usuário GitHub e o namespace io.github.ysalitrynskyi do registro MCP), então a publicação deve ser feita enquanto estiver conectado como essa conta.

1. Aumente a versão em três lugares e mantenha-os idênticos: package.json, server.json (no nível superior e o packages[0].version), e SERVER_VERSION em src/server.ts.
2. Finalize: faça commit para main e envie. CI (.github/workflows/ci.yml) executa build + test — ele não publica.
3. Publique no npm (como usuário npm ysalitrynskyi):

   npm login
   npm publish        # prepublishOnly runs the build
   

4. Publique no registro MCP (como usuário GitHub ysalitrynskyi):

   mcp-publisher validate      # optional, offline check
   mcp-publisher login github  # interactive browser OAuth
   mcp-publisher publish
   

Smithery (smithery.yaml) e Glama (glama.json) rastreiam a publicação npm/registro automaticamente — nenhuma etapa separada.

Licença

MIT © ysalitrynskyi. Parte do projeto opn.onl.