VK MCP Server

VK MCP Server

Servidor Model Context Protocol (MCP) para la API de la red social VK (VKontakte)

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

Permite que asistentes de IA como Claude interactúen con VK a través de una interfaz estandarizada.

---

Muros, comunidades y perfiles en un host que admite MCP Apps. El modelo obtiene los mismos datos estructurados de cualquier manera — esto es lo que la persona ve.

---

Características

• 25 herramientas para usuarios, muros, comunidades, fotos, historias, mensajes de comunidad, me gusta y estadísticas
• Bandeja de entrada de tu comunidad: lista conversaciones no leídas, léelas y responde como la comunidad — el asistente redacta, tú apruebas, él envía
• Lee y escribe como una comunidad: con un token de comunidad y una clave de servicio juntos, el asistente lee muros, perfiles y comunidades, y publica, comenta, publica historias y responde mensajes como tu comunidad. Las escrituras se marcan como tales para que tu cliente pueda preguntar primero. Algunas herramientas (búsqueda, me gusta, estadísticas, edición) necesitan un token de usuario completo, que VK ya no emite para aplicaciones nuevas — la guía de configuración enumera exactamente qué alcanza cada token
• Salida estructurada: cada herramienta declara un esquema de salida, así el modelo obtiene datos tipados en lugar de un blob JSON que tiene que parsear del texto
• Paginación que se explica sola: los resultados de listas dicen cuántas coincidencias existen y qué offset continúa desde aquí, así el modelo puede recorrer un muro en lugar de detenerse en los primeros veinte posts
• Cosas que puedes ver: en hosts que admiten MCP Apps — Claude, Claude Desktop, VS Code Copilot, Goose — muros, comunidades y perfiles se renderizan como tarjetas: posts con sus fotos y vistas previas de clips, comunidades con su banner y tamaño, perfiles con avatar y seguimiento. En cualquier otro lugar se comporta exactamente como antes
• Prompts: flujos de trabajo listos — resumen de comunidad, informe de engagement, instantánea de audiencia, búsqueda de comunidad, bandeja de entrada de comunidad
• Resiliente: timeouts de solicitud, backoff automático cuando VK limita la tasa, y mensajes claros para captchas y fallos HTTP
• Honesto sobre tokens: VK tiene tres tipos y difieren enormemente en alcance. --check nombra cuál tienes y sondea qué puede hacer realmente, --login recorre el flujo VK ID para el tipo de lectura, y cada error de VK lleva la solución en lugar de solo el código
• Probado: 84 pruebas que ejecutan el servidor real sobre el protocolo MCP

Inicio Rápido

Claude Desktop — un clic

Descarga el último paquete .mcpb desde la página de releases y ábrelo. Instala el servidor, pide tu token de VK en un campo de formulario y lo almacena de forma segura — sin Node.js, sin archivos de configuración, sin terminal.

VS Code — un clic

VS Code pide tu token de VK y lo mantiene fuera del archivo de configuración. Desde una terminal en su lugar:

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

npm

npx vk-mcp-server

O instala globalmente con npm install -g vk-mcp-server.

Registro MCP

También disponible en el Registro MCP oficial:

io.github.bulatko/vk

Cómo Obtener un Token de Acceso de VK

Para permitir que el asistente publique, necesitas un token de comunidad. Abre una comunidad que gestiones → Gestionar → Uso de API → Tokens de acceso → Crear token, marcando wall, photos, stories, messages y manage. Tres clics, sin aplicación, nunca expira, no está vinculado a navegador ni IP. Publica, comenta y publica historias como la comunidad.

Añade una clave de servicio junto a él, y el asistente también lee muros. VK rechaza las lecturas de muro con token de comunidad (error 27). Configura la clave de servicio desde la página de configuración de tu aplicación VK como VK_SERVICE_KEY, y el servidor hace cada lectura que el token rechaza con la clave en su lugar — las escrituras nunca van a ella:

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

Lo que ningún token que VK emite para una aplicación nueva puede hacer, verificado contra la API en vivo en octubre de 2026: editar o eliminar posts, subir fotos de muro, leer estadísticas, me gusta, álbumes de fotos, búsqueda o el newsfeed. VK los reserva para tokens de usuario completos, que ya no concede.

Para lecturas públicas solamente, la clave de servicio por sí sola es suficiente (como VK_SERVICE_KEY o VK_ACCESS_TOKEN), o inicia sesión como tú mismo:

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

Vale la pena saberlo antes de pasar una noche en ello: --login devuelve un token VK ID (vk2.a…), que VK emite para iniciar sesión en lugar de para la API. Lee perfiles públicos, muros e información de comunidad; publicar, fotos, amigos, feeds y estadísticas responden todos error 1051, cualesquiera que sean los alcances que solicites. El flujo más antiguo que concedía tokens de usuario completos ahora rechaza aplicaciones recién creadas por completo. npx vk-mcp-server --check nombra qué tipo tienes y qué alcanza.

Usa tu propia aplicación en lugar de un App ID de otro lugar: un token muere con la aplicación que lo emitió, y el error no da ninguna pista de que esto es lo que pasó.

📖 Guía de configuración completa — cada paso con las pantallas exactas, qué desbloquean los alcances, instalaciones remotas y qué significa cada error.

Configuración

Claude Desktop

Añade a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %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

Añade al .mcp.json de tu proyecto:

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

Variables de entorno

Variable	Requerida	Predeterminado	Propósito
VK_ACCESS_TOKEN	para llamadas de herramientas	—	El token con el que actúan las herramientas, normalmente un token de comunidad. El servidor arranca y lista sus herramientas sin uno; llamar a una herramienta entonces devuelve un error que lo dice
VK_SERVICE_KEY	no	—	Clave de servicio de tu aplicación VK. Las lecturas que el token de acceso rechaza (un muro, bajo un token de comunidad) se hacen con ella; nunca se usa para escrituras. Por sí sola, es suficiente para lecturas públicas
VK_TIMEOUT_MS	no	30000	Aborta una solicitud de VK que se cuelga más tiempo que esto
VK_API_BASE	no	https://api.vk.com/method	Apunta el servidor a un espejo de API o proxy

VK limita la tasa de tokens de usuario a unas pocas llamadas por segundo. Cuando responde con error 6 (demasiadas solicitudes), el servidor hace backoff y reintenta hasta tres veces antes de rendirse, así que ráfagas cortas de llamadas de herramientas no fallan por completo.

Línea de comandos

Comando	Qué hace
npx vk-mcp-server	Ejecuta el servidor MCP (esto es lo que tu cliente llama)
npx vk-mcp-server --login <APP_ID>	Obtiene un token a través de VK ID en tu navegador
npx vk-mcp-server --check	Informa qué es tu token y qué herramientas puede usar
npx vk-mcp-server --help	Lista los comandos y las variables de entorno

Solución de problemas

Empieza con:

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

Identifica cuál de los tres tipos de token tienes — usuario, comunidad o servicio — y sondea qué puede alcanzar realmente ese token, así lo descubres de antemano en lugar de descubrirlo herramienta por herramienta. Nunca llama a un método de escritura.

Casos comunes:

Lo que ves	Qué significa
error 8: Application is blocked	La aplicación VK que emitió el token está bloqueada. Cada token de ella falla de esta manera, por muy válido que parezca el token. Crea tu propia aplicación y emite un token nuevo.
error 5: User authorization failed	El token expiró o fue revocado — ejecuta --login de nuevo.
error 27: Group authorization failed	Un token de comunidad pidió algo que VK le reserva — leer un muro, por ejemplo. Configura VK_SERVICE_KEY y las lecturas van a la clave; las ediciones, eliminaciones y estadísticas permanecen cerradas.
error 1051 o error 28	Un token VK ID o una clave de servicio pidió un método cerrado para él. Para publicar, usa un token de comunidad.
error 15: Access denied	Los datos están restringidos — un perfil privado, o una comunidad que oculta a sus miembros.
error 5 con subcode 1130	VK vinculó el token a la IP que lo autorizó, y el servidor está en una diferente. Común cuando el servidor corre en un VPS pero iniciaste sesión desde tu portátil. Obtén el token en la máquina que ejecuta el servidor, o usa un token de comunidad.
Security Error al autorizar	El flujo OAuth implícito antiguo. Usa --login, que hace el flujo VK ID actual.
No VK token configured en cada herramienta	El servidor está corriendo pero tu cliente nunca le pasó VK_ACCESS_TOKEN. Revisa el bloque env en la configuración de tu cliente — un token en tu shell no llega a un servidor que el cliente inicia por sí mismo.

El servidor convierte estos en mensajes que dicen qué hacer, así que el modelo puede normalmente explicar la solución sin que leas esta tabla.

Herramientas Disponibles

Las herramientas marcadas con ✏️ cambian algo en VK — publican, editan, eliminan o se unen en nombre de quien posee el token de acceso. Cada herramienta también lleva anotaciones MCP (readOnlyHint, destructiveHint), así que un cliente puede autoaprobar consultas mientras aún pregunta antes de que un post sea editado o eliminado.

Usuarios

Herramienta	Descripción
vk_users_get	Obtiene perfiles de usuario por IDs o nombres de pantalla
vk_users_search	Busca usuarios por nombre, ciudad, edad y otros criterios

Muro

Herramienta	Descripción
vk_wall_get	Obtiene posts del muro de usuario/comunidad
vk_wall_get_by_id	Obtiene posts específicos por {owner_id}_{post_id}
vk_wall_post	✏️ Publica un post nuevo
vk_wall_edit	✏️ Edita un post existente
vk_wall_delete	✏️ Elimina un post
vk_wall_create_comment	✏️ Añade un comentario a un post

Grupos

Herramienta	Descripción
vk_groups_get	Obtiene la lista de comunidades del usuario
vk_groups_get_by_id	Obtiene información de comunidad por ID
vk_groups_search	Busca comunidades por nombre y criterios
vk_groups_get_members	Obtiene miembros de la comunidad
vk_groups_join	✏️ Se une a una comunidad o solicita unirse

Fotos

Herramienta	Descripción
vk_photos_get	Obtiene fotos de álbumes
vk_photos_upload_wall	✏️ Sube una foto y obtiene una cadena de adjunto para vk_wall_post — necesita un token de usuario completo; VK rechaza tokens de comunidad aquí

Historias

Herramienta	Descripción
vk_stories_post_photo	✏️ Publica una historia de foto, personal o en nombre de una comunidad
vk_stories_post_video	✏️ Publica una historia de video, personal o en nombre de una comunidad

Mensajes de comunidad

Necesita un token de comunidad con el derecho messages, y mensajes activados en la configuración de la comunidad. VK permite que una comunidad escriba solo a personas que le escribieron primero o que permitieron sus mensajes.

Herramienta	Descripción
vk_messages_get_conversations	Lista la bandeja de entrada, más reciente primero; filter: "unread" muestra qué espera una respuesta
vk_messages_get_history	Lee una conversación
vk_messages_send	✏️ Responde como la comunidad — llega a una persona real, así que los clientes deberían preguntar primero
vk_messages_mark_as_read	✏️ Marca una conversación como leída

Otros

Herramienta	Descripción
vk_friends_get	Obtiene la lista de amigos del usuario
vk_newsfeed_get	Obtiene el newsfeed del usuario
vk_likes_get	Obtiene usuarios que dieron me gusta a un objeto, con conteos de reacciones
vk_stats_get	Obtiene estadísticas de comunidad (solo administradores)

Prompts

Los prompts aparecen en tu cliente como flujos de trabajo listos — elige uno, completa la comunidad, y el modelo sabe qué herramientas usar.

Prompt	Qué hace
community_digest	Lee publicaciones recientes y resume temas, destacados y ritmo de publicación
engagement_report	Clasifica publicaciones por me gusta y por comentarios, y explica qué tienen en común las ganadoras
audience_snapshot	Toma una muestra de miembros y describe la audiencia por sexo, ciudad y actividad
publish_post	Redacta una publicación con el tono propio de la comunidad, la muestra para aprobación y la publica
find_communities	Busca comunidades sobre un tema y compara las candidatas
community_inbox	Revisa los mensajes no leídos, resume cada uno y redacta respuestas; envía solo lo que apruebes

Ejemplos de uso

Una vez configurado, puedes pedirle a Claude:

• "Obtén información sobre el perfil de VK de Pavel Durov"
• "Muéstrame las últimas 5 publicaciones de la comunidad oficial de VK"
• "Publica '¡Hola Mundo!' en mi muro"
• "Obtén la lista de comunidades de las que soy miembro"
• "Muéstrame mi feed de noticias"

Conversación de ejemplo

Un intercambio real: los números siguientes llegaron desde VK mientras se escribía esto.

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.

El modelo recibe cada uno de esos números como campos tipados en lugar de texto que deba analizar, porque cada herramienta declara un esquema de salida.

Registro de cambios

Consulta CHANGELOG.md.

Pruebas

Ejecuta la suite de pruebas:

npm test

Ejecuta las pruebas con cobertura:

npm run test:coverage

Referencia de la API

Este servidor envuelve la API de VK v5.199. Para documentación detallada de parámetros, consulta:

• Métodos de la API de VK
• Objetos de la API de VK

Notas de seguridad

• Nunca compartas tu token de acceso
• El alcance offline proporciona un token que no caduca
• Revisa los permisos antes de autorizar
• Para producción, considera usar un token de servicio

Contribuciones

¡Las contribuciones son bienvenidas! Lee primero las Directrices de contribución.

1. Haz un fork del repositorio
2. Crea tu rama de funcionalidad (git checkout -b feature/amazing-feature)
3. Haz commit de tus cambios (git commit -m 'Add some amazing feature')
4. Sube la rama (git push origin feature/amazing-feature)
5. Abre una solicitud de extracción

Licencia

MIT © 2026 bulatko

Enlaces

• Paquete npm
• Registro MCP
• Documentación de la API de VK
• Protocolo de Contexto de Modelo

---

Hecho con ❤️ para el ecosistema MCP