Hermes VK Messenger Plugin
A VKontakte plugin for Hermes Agent: a community bot receives direct and group messages over Long Poll API and the agent replies as the community
- 1 ★ on the repository
- Last commit
Extended access
Why this level
- The plugin reads the community's correspondence and replies as it using the group token
- With the `open` policy the bot answers anyone who writes, and model load and costs fall on you
Install
- Services
Manual install
cp -r hermes-vk-plugin ~/.hermes/plugins/vk && hermes plugins enable vkFrom the directory with the repository clone. Install aiohttp into the Hermes environment first.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The plugin reads the community's correspondence and replies as it using the group token
- With the `open` policy the bot answers anyone who writes, and model load and costs fall on you
This is third-party code. Review the repository files before installing.
What it does
The plugin connects Hermes Agent to VKontakte as one more messaging platform. It uses the community's Bots Long Poll API: the adapter requests a Long Poll server through `groups.getLongPollServer`, starts an endless polling loop and receives `message_new` events. Each incoming message becomes a Hermes event, and the agent's reply goes out through `messages.send` as the group. Direct messages and group chats work, and the Callback API event format is supported. The platform registers automatically through `_missing_()`, so Hermes source code needs no edits. The `open`, `allowlist` and `disabled` policies control access separately for direct messages and chats, and `VK_ALLOWED_USERS` sets the list of allowed users. The repository holds just four files: `plugin.yaml` with metadata, `__init__.py` registering the platform, `adapter.py` with the `VKAdapter` class and the README. The connector forces IPv4 because VKontakte does not answer over IPv6 in WSL.
Who it is for. VKontakte community owners and Hermes Agent users who want to give the agent a channel for talking with subscribers through group messages.
Good fit when
- A VKontakte community receives questions in direct messages and a Hermes agent answers them
- The agent should work in a community chat and see new messages in real time
- Access must be limited to a user list so the bot does not answer strangers
- Scheduled notifications go to a set channel through `VK_HOME_CHANNEL`
- Hermes runs in WSL, where ordinary VKontakte connections over IPv6 do not go through
Not a fit when
- The agent does not run on Hermes: the plugin is written for its platform registry and adapter class
- You need a personal profile rather than a community: the bot Long Poll is available only to a community with a group token
- You need wall posts, ad accounts and analytics: the plugin reads and sends messages and has nothing else
- Your Hermes version lacks `Platform._missing_()`: the plugin is built on that mechanism
Example request
Let the agent answer subscriber questions in group messages and explain to new members how to use the service.Limitations
Hermes Agent with `Platform._missing_()` support, Python 3.11, the aiohttp package and a VKontakte community token with message rights are required. The token and group id go into `.env` as `VK_GROUP_TOKEN` and `VK_GROUP_ID`.
Before `hermes gateway run`, old processes must be stopped with `pkill -f 'hermes gateway'`, otherwise a guard blocks startup. The `connect()` class method gained an `is_reconnect` parameter for gateway compatibility.
The plugin is small and written by one author. The repository has no tests and no license file, but the README states the MIT license. The group token opens the community's correspondence, so keep it in the environment only.
How to disable. Disable the plugin with `hermes plugins disable vk` or delete the `~/.hermes/plugins/vk` folder. Revoke the group token in the VKontakte community settings.
FAQ
How do I connect VKontakte to Hermes Agent?
Copy the plugin with `cp -r hermes-vk-plugin ~/.hermes/plugins/vk`, install aiohttp and enable the plugin with `hermes plugins enable vk`. Set `VK_GROUP_TOKEN` and `VK_GROUP_ID` in `.env`, then run `hermes gateway run --verbose`.
Which VKontakte token is needed?
A community token with message rights. It is issued in the group settings, and the agent answers users as that group.
How do I limit who the bot answers?
The `dm_policy` and `group_policy` settings accept `open`, `allowlist` and `disabled`. `VK_ALLOWED_USERS` sets the user list and `VK_ALLOW_ALL_USERS=true` allows everyone.
Why does the plugin force IPv4?
In WSL VKontakte does not answer over IPv6, so the connector uses IPv4 only. This is meant for environments without working IPv6.
What if the Hermes gateway does not start?
Stop old processes with `pkill -f 'hermes gateway'` and start the gateway again. A guard blocks a second instance until the first one is finished.
Discussion
No questions or reviews yet.
Related
All VK toolsHermes VK Adapter
hermes-vk-adapter
A plugin that connects VK community private messages to Hermes Agent through Bots Long Poll with no public address or webhook
hermes-vk (TemArt90)
hermes-vk
A VK channel for Hermes Agent: Long Poll, buttons and model choice in the dialog, voice, images, cron report delivery and pairing approval
Claude Code channel plugin: chat with an agent session through a VK community from mobile or web
vk-mcp (alexfisenkov)
vk-mcp
Remote MCP server for VK communities: 50 tools, posts, comments, dialogs, photos, video and products, with writing off by default
VK to Telegram bridge MCP
vk-tg-bridge
A 4-tool MCP server that pulls VK wall posts, filters them by rules and publishes them to Telegram via the Bot API
VK MCP Server (ORAMAN)
VK-MCP-Server
Local MCP server for the VK API: search for people and cities, profiles, photos and video with an HTML gallery, a token pool and a SQLite cache
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| Hermes VK Messenger Plugin (this card) | no | 1 | |
| Hermes MAX Gateway | no | 17 | a Hermes gateway for the MAX messenger rather than VKontakte |
| Alice Voice for Hermes | no | 11 | a voice plugin for Alice with no community messages |
README in short
The README briefly covers capabilities, install steps, `.env` and `config.yaml` settings, gateway launch, how the adapter works and known quirks. The author is listed as Arnis, license MIT.