VK MCP Server

VK MCP Server

Servidor Model Context Protocol (MCP) para a API da rede social VK (VKontakte)

English · Русский · Сайт (RU)

Permite que assistentes de IA como o Claude interajam com o VK por meio de uma interface padronizada.

---

Murais, comunidades e perfis em um host compatível com MCP Apps. O modelo recebe os mesmos dados estruturados de qualquer forma — isto é o que a pessoa vê.

---

Recursos

• 25 ferramentas entre usuários, murais, comunidades, fotos, histórias, mensagens da comunidade, curtidas e estatísticas
• Caixa de entrada da sua comunidade: liste conversas não lidas, leia-as e responda como a comunidade — o assistente redige, você aprova, ele envia
• Leia e escreva como uma comunidade: com um token de comunidade e uma chave de serviço juntos, o assistente lê murais, perfis e comunidades e publica, comenta, publica histórias e responde mensagens como sua comunidade. Escritas são marcadas como tais para que seu cliente possa perguntar primeiro. Algumas ferramentas (busca, curtidas, estatísticas, edição) precisam de um token de usuário completo, que o VK não emite mais para novos aplicativos — o guia de configuração lista exatamente o que cada token alcança
• Saída estruturada: cada ferramenta declara um esquema de saída, então o modelo recebe dados tipados em vez de um bloco JSON que ele precisa extrair do texto
• Paginação que se explica: resultados de listas dizem quantas correspondências existem e qual deslocamento continua a partir daqui, então o modelo pode percorrer um mural em vez de parar nos primeiros vinte posts
• Coisas que você pode ver: em hosts que suportam MCP Apps — Claude, Claude Desktop, VS Code Copilot, Goose — murais, comunidades e perfis são renderizados como cartões: posts com suas fotos e prévias de clipes, comunidades com seu banner e tamanho, perfis com avatar e seguidores. Em qualquer outro lugar, comporta-se exatamente como antes
• Prompts: fluxos de trabalho prontos — resumo da comunidade, relatório de engajamento, instantâneo do público, busca de comunidades, caixa de entrada da comunidade
• Resiliente: timeouts de requisição, backoff automático quando o VK limita a taxa, e mensagens claras para captchas e falhas HTTP
• Honesto sobre tokens: o VK tem três tipos e eles diferem enormemente em alcance. --check nomeia qual você possui e testa o que ele pode realmente fazer, --login percorre o fluxo VK ID para o tipo de leitura, e cada erro do VK carrega a correção em vez de apenas o código
• Testado: 84 testes dirigindo o servidor real pelo protocolo MCP

Início Rápido

Claude Desktop — um clique

Baixe o pacote .mcpb mais recente da página de releases e abra-o. Ele instala o servidor, pede seu token VK em um campo de formulário e o armazena com segurança — sem Node.js, sem arquivos de configuração, sem terminal.

VS Code — um clique

O VS Code pede seu token VK e o mantém fora do arquivo de configuração. Pelo terminal, em vez disso:

code --add-mcp '{"name":"vk","command":"npx","args":["-y","vk-mcp-server"],"env":{"VK_ACCESS_TOKEN":"your_token"}}'

npm

npx vk-mcp-server

Ou instale globalmente com npm install -g vk-mcp-server.

Registro MCP

Também disponível no Registro MCP oficial:

io.github.bulatko/vk

Obtendo Token de Acesso VK

Para permitir que o assistente publique, você precisa de um token de comunidade. Abra uma comunidade que você gerencia → Gerenciar → Uso da API → Tokens de acesso → Criar token, marcando wall, photos, stories, messages e manage. Três cliques, sem aplicativo, nunca expira, não vinculado a navegador ou IP. Ele publica, comenta e publica histórias como a comunidade.

Adicione uma chave de serviço ao lado dele, e o assistente também lê murais. O VK recusa leituras de mural com token de comunidade (erro 27). Defina a chave de serviço da página de configurações do seu aplicativo VK como VK_SERVICE_KEY, e o servidor faz cada leitura que o token é recusado com a chave — escritas nunca vão para ela:

"env": {
  "VK_ACCESS_TOKEN": "vk1.a...community token",
  "VK_SERVICE_KEY": "...service key"
}

O que nenhum token que o VK emite para um novo aplicativo pode fazer, verificado contra a API ao vivo em outubro de 2026: editar ou excluir posts, enviar fotos para o mural, ler estatísticas, curtidas, álbuns de fotos, busca ou feed de notícias. O VK mantém isso para tokens de usuário completos, que ele não concede mais.

Para leituras públicas apenas, a chave de serviço sozinha é suficiente (como VK_SERVICE_KEY ou VK_ACCESS_TOKEN), ou entre como você mesmo:

npx vk-mcp-server --login <YOUR_APP_ID>

Vale saber antes de gastar uma noite nisso: --login retorna um token VK ID (vk2.a…), que o VK emite para login em vez de para a API. Ele lê perfis públicos, murais e informações de comunidades; publicar, fotos, amigos, feeds e estatísticas respondem todos com error 1051, quaisquer escopos que você solicite. O fluxo mais antigo que concedia tokens de usuário completos agora recusa aplicativos recém-criados completamente. npx vk-mcp-server --check nomeia qual tipo você possui e o que ele alcança.

Use seu próprio aplicativo em vez de um App ID de outro lugar: um token morre com o aplicativo que o emitiu, e o erro não dá nenhuma dica de que foi isso que aconteceu.

📖 Guia de configuração completo — cada passo com as telas exatas, o que os escopos desbloqueiam, instalações remotas e o que cada erro significa.

Configuração

Claude Desktop

Adicione a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "vk": {
      "command": "npx",
      "args": ["-y", "vk-mcp-server"],
      "env": {
        "VK_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}

Claude Code

Adicione ao .mcp.json do seu projeto:

{
  "mcpServers": {
    "vk": {
      "command": "npx",
      "args": ["-y", "vk-mcp-server"],
      "env": {
        "VK_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}

Variáveis de ambiente

Variável	Obrigatória	Padrão	Propósito
VK_ACCESS_TOKEN	para chamadas de ferramentas	—	O token com o qual as ferramentas agem, geralmente um token de comunidade. O servidor inicia e lista suas ferramentas sem um; chamar uma ferramenta então retorna um erro dizendo isso
VK_SERVICE_KEY	não	—	Chave de serviço do seu aplicativo VK. Leituras que o token de acesso é recusado (um mural, sob um token de comunidade) são feitas com ela; nunca usada para escritas. Sozinha, é suficiente para leituras públicas
VK_TIMEOUT_MS	não	30000	Aborta uma requisição VK que trava por mais tempo que isso
VK_API_BASE	não	https://api.vk.com/method	Aponta o servidor para um espelho de API ou proxy

O VK limita a taxa de tokens de usuário a algumas chamadas por segundo. Quando ele responde com erro 6 (muitas requisições), o servidor faz backoff e tenta novamente até três vezes antes de desistir, então rajadas curtas de chamadas de ferramentas não falham completamente.

Linha de comando

Comando	O que faz
npx vk-mcp-server	Executa o servidor MCP (isto é o que seu cliente chama)
npx vk-mcp-server --login <APP_ID>	Obtém um token pelo VK ID no seu navegador
npx vk-mcp-server --check	Relata o que seu token é e quais ferramentas ele pode usar
npx vk-mcp-server --help	Lista os comandos e variáveis de ambiente

Solução de Problemas

Comece com:

VK_ACCESS_TOKEN=your_token npx vk-mcp-server --check

Ele identifica qual dos três tipos de token você tem — usuário, comunidade ou serviço — e testa o que esse token pode realmente alcançar, então você descobre de antemão em vez de descobrir ferramenta por ferramenta. Ele nunca chama um método de escrita.

Casos comuns:

O que você vê	O que significa
error 8: Application is blocked	O aplicativo VK que emitiu o token está bloqueado. Todo token dele falha dessa forma, por mais válido que o token pareça. Crie seu próprio aplicativo e emita um novo token.
error 5: User authorization failed	O token expirou ou foi revogado — execute --login novamente.
error 27: Group authorization failed	Um token de comunidade pediu algo que o VK mantém dele — ler um mural, por exemplo. Defina VK_SERVICE_KEY e leituras vão para a chave; edições, exclusões e estatísticas permanecem fechadas.
error 1051 ou error 28	Um token VK ID ou uma chave de serviço pediu um método fechado para ele. Para publicar, use um token de comunidade.
error 15: Access denied	Os dados são restritos — um perfil privado, ou uma comunidade que esconde seus membros.
error 5 com subcode 1130	O VK vinculou o token ao IP que o autorizou, e o servidor está em um diferente. Comum quando o servidor roda em um VPS, mas você entrou do seu laptop. Obtenha o token na máquina que executa o servidor, ou use um token de comunidade.
Security Error ao autorizar	O fluxo OAuth implícito antigo. Use --login, que faz o fluxo VK ID atual.
No VK token configured em toda ferramenta	O servidor está rodando, mas seu cliente nunca passou VK_ACCESS_TOKEN para ele. Verifique o bloco env na configuração do seu cliente — um token no seu shell não alcança um servidor que o cliente inicia sozinho.

O servidor transforma isso em mensagens que dizem o que fazer, então o modelo pode geralmente explicar a correção sem você ler esta tabela.

Ferramentas Disponíveis

Ferramentas marcadas com ✏️ mudam algo no VK — elas publicam, editam, excluem ou entram em nome de quem possui o token de acesso. Cada ferramenta também carrega anotações MCP (readOnlyHint, destructiveHint), então um cliente pode aprovar automaticamente consultas enquanto ainda pergunta antes de um post ser editado ou excluído.

Usuários

Ferramenta	Descrição
vk_users_get	Obter perfis de usuários por IDs ou nomes de tela
vk_users_search	Buscar usuários por nome, cidade, idade e outros critérios

Mural

Ferramenta	Descrição
vk_wall_get	Obter posts do mural de usuário/comunidade
vk_wall_get_by_id	Obter posts específicos por {owner_id}_{post_id}
vk_wall_post	✏️ Publicar um novo post
vk_wall_edit	✏️ Editar um post existente
vk_wall_delete	✏️ Excluir um post
vk_wall_create_comment	✏️ Adicionar comentário a um post

Comunidades

Ferramenta	Descrição
vk_groups_get	Obter lista de comunidades do usuário
vk_groups_get_by_id	Obter informações da comunidade por ID
vk_groups_search	Buscar comunidades por nome e critérios
vk_groups_get_members	Obter membros da comunidade
vk_groups_join	✏️ Entrar em uma comunidade ou solicitar entrada

Fotos

Ferramenta	Descrição
vk_photos_get	Obter fotos de álbuns
vk_photos_upload_wall	✏️ Enviar uma foto e obter uma string de anexo para vk_wall_post — precisa de um token de usuário completo; o VK recusa tokens de comunidade aqui

Histórias

Ferramenta	Descrição
vk_stories_post_photo	✏️ Publicar uma história de foto, pessoal ou em nome de uma comunidade
vk_stories_post_video	✏️ Publicar uma história de vídeo, pessoal ou em nome de uma comunidade

Mensagens da comunidade

Precisa de um token de comunidade com o direito messages, e mensagens ativadas nas configurações da comunidade. O VK permite que uma comunidade escreva apenas para pessoas que escreveram para ela primeiro ou permitiram suas mensagens.

Ferramenta	Descrição
vk_messages_get_conversations	Listar a caixa de entrada, mais recentes primeiro; filter: "unread" mostra o que aguarda resposta
vk_messages_get_history	Ler uma conversa
vk_messages_send	✏️ Responder como a comunidade — alcança uma pessoa real, então clientes devem perguntar primeiro
vk_messages_mark_as_read	✏️ Marcar uma conversa como lida

Outros

Ferramenta	Descrição
vk_friends_get	Obter lista de amigos do usuário
vk_newsfeed_get	Obter feed de notícias do usuário
vk_likes_get	Obter usuários que curtiram um objeto, com contagens de reações
vk_stats_get	Obter estatísticas da comunidade (somente administradores)

Prompts

Prompts aparecem no seu cliente como fluxos de trabalho prontos — escolha um, preencha a comunidade, e o modelo sabe quais ferramentas usar.

Prompt	O que faz
community_digest	Lê postagens recentes e resume temas, destaques e ritmo
engagement_report	Classifica postagens por curtidas e por comentários e explica o que os vencedores têm em comum
audience_snapshot	Amostra membros e descreve o público por sexo, cidade e atividade
publish_post	Redige uma postagem no tom da própria comunidade, mostra para aprovação e publica
find_communities	Pesquisa comunidades sobre um tópico e compara os candidatos
community_inbox	Analisa mensagens não lidas, resume cada uma e redige respostas; envia apenas o que você aprovar

Exemplos de Uso

Depois de configurado, você pode pedir ao Claude:

• "Obter informações sobre o perfil de Pavel Durov no VK"
• "Mostrar as 5 últimas postagens da comunidade oficial do VK"
• "Publicar 'Hello World!' no meu mural"
• "Obter a lista de comunidades das quais sou membro"
• "Mostrar meu feed de notícias"

Exemplo de Conversa

Uma troca real — os números abaixo vieram do VK enquanto isto era escrito.

You:    How big is the VK Mini Apps community, and how are its recent posts doing?

Claude: [vk_groups_get_by_id  group_ids="apiclub", fields="members_count,activity"]
        [vk_wall_get          domain="apiclub", count=3]

        VK Mini Apps (@vkappsdev, id 166562603) — 245,457 members, filed under
        Programming, with 898 posts on the wall. The three most recent:

        21 Jan   22,653 views   46 likes   15 reposts   "Готовы сделать этот год прорывным?..."
        20 Jul      529 views   18 likes    0 reposts   (photo post, no text)
        13 Jul    3,782 views   11 likes    3 reposts   "Суперсила игр и приложений в соцсети..."

        The January post reached forty times the audience of the July ones —
        worth a look at what it did differently.

O modelo recebe cada um desses números como campos tipados, em vez de texto que precisa analisar, porque cada ferramenta declara um esquema de saída.

Changelog

Veja CHANGELOG.md.

Testes

Execute a suíte de testes:

npm test

Execute testes com cobertura:

npm run test:coverage

Referência da API

Este servidor encapsula a API do VK v5.199. Para documentação detalhada de parâmetros, veja:

• Métodos da API do VK
• Objetos da API do VK

Notas de Segurança

• Nunca compartilhe seu token de acesso
• O escopo offline fornece um token sem expiração
• Revise as permissões antes de autorizar
• Para produção, considere usar um token de serviço

Contribuindo

Contribuições são bem-vindas! Leia as Diretrizes de Contribuição primeiro.

1. Faça um fork do repositório
2. Crie sua branch de recurso (git checkout -b feature/amazing-feature)
3. Faça commit das suas alterações (git commit -m 'Add some amazing feature')
4. Envie para a branch (git push origin feature/amazing-feature)
5. Abra um Pull Request

Licença

MIT © 2026 bulatko

Links

• Pacote npm
• Registro MCP
• Documentação da API do VK
• Model Context Protocol

---

Feito com ❤️ para o ecossistema MCP