VK MCP Server
Features
- 25 tools across users, walls, communities, photos, stories, community messages, likes and statistics
- Your community's inbox: list unread conversations, read them, and reply as the community — the assistant drafts, you approve, it sends
- Read and write as a community: with a community token and a service key together, the assistant reads walls, profiles and communities and posts, comments, publishes stories and answers messages as your community. Writes are marked as such so your client can ask first. Some tools (search, likes, statistics, editing) need a full user token, which VK no longer issues to new apps — the setup guide lists exactly what each token reaches
- Structured output: every tool declares an output schema, so the model gets typed data instead of a JSON blob it has to parse out of text
- Pagination that explains itself: list results say how many matches exist and which offset continues from here, so the model can page through a wall instead of stopping at the first twenty posts
- Things you can look at: on hosts that support MCP Apps — Claude, Claude Desktop, VS Code Copilot, Goose — walls, communities and profiles render as cards: posts with their photos and clip previews, communities with their banner and size, profiles with avatar and following. Everywhere else it behaves exactly as before
- Prompts: ready-made workflows — community digest, engagement report, audience snapshot, community search, community inbox
- Resilient: request timeouts, automatic backoff when VK rate-limits, and clear messages for captchas and HTTP failures
- Honest about tokens: VK has three kinds and they differ enormously in
reach.
--checknames which one you hold and probes what it can actually do,--loginwalks the VK ID flow for the reading kind, and every VK error carries the fix rather than the code alone - Tested: 140+ tests driving the real server over the MCP protocol
Quick Start
Claude Desktop — one click
Download the latest .mcpb bundle from the
releases page and
open it. It installs the server, asks for your VK token in a form field, and
stores it securely — no Node.js, no config files, no terminal.
VS Code — one click
VS Code prompts for your VK token and keeps it out of the config file. From a terminal instead:
code --add-mcp '{"name":"vk","command":"npx","args":["-y","vk-mcp-server"],"env":{"VK_ACCESS_TOKEN":"your_token"}}'
npm
npx vk-mcp-server
Or install globally with npm install -g vk-mcp-server.
MCP Registry
Also available in the official MCP Registry:
io.github.bulatko/vk
Getting VK Access Token
To let the assistant post, you need a community token. Open a community you
manage → Manage → API usage → Access tokens → Create token,
ticking wall, photos, stories, messages and manage. Three clicks, no
app, never expires, tied to no browser or IP. It posts, comments and publishes
stories as the community.
Add a service key next to it, and the assistant reads walls too. VK refuses
a community token wall reads (error 27). Set the service key from your VK app's
settings page as VK_SERVICE_KEY, and the server makes every read the token is
refused with the key instead — writes never go to it:
"env": {
"VK_ACCESS_TOKEN": "vk1.a...community token",
"VK_SERVICE_KEY": "...service key"
}
What no token VK issues to a new app can do, checked against the live API in October 2026: edit or delete posts, upload wall photos, read statistics, likes, photo albums, search or the newsfeed. VK keeps those for full user tokens, which it no longer grants.
For public reads alone, the service key on its own is enough (as
VK_SERVICE_KEY or VK_ACCESS_TOKEN), or sign in as yourself:
npx vk-mcp-server --login <YOUR_APP_ID>
Worth knowing before you spend an evening on it: --login returns a VK ID
token (vk2.a…), which VK issues for signing in rather than for the API. It
reads public profiles, walls and community info; posting, photos, friends,
feeds and statistics all answer error 1051, whatever scopes you request. The
older flow that granted full user tokens now refuses newly created apps
outright. npx vk-mcp-server --check names which kind you hold and what it
reaches.
Use your own app rather than an App ID from somewhere else: a token dies with the app that issued it, and the error gives no hint that this is what happened.
📖 Full setup guide — every step with the exact screens, what the scopes unlock, remote installs, and what each error means.
Configuration
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %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
Add to your project's .mcp.json:
{
"mcpServers": {
"vk": {
"command": "npx",
"args": ["-y", "vk-mcp-server"],
"env": {
"VK_ACCESS_TOKEN": "your_access_token_here"
}
}
}
}
Environment variables
VK rate-limits user tokens to a few calls per second. When it answers with error 6 (too many requests), the server backs off and retries up to three times before giving up, so short bursts of tool calls do not fail outright.
Command line
Troubleshooting
Start with:
VK_ACCESS_TOKEN=your_token npx vk-mcp-server --check
It identifies which of the three token types you have — user, community or service — and probes what that token can actually reach, so you find out up front instead of discovering it tool by tool. It never calls a write method.
Common cases:
The server turns these into messages that say what to do, so the model can usually explain the fix without you reading this table.
Available Tools
Tools marked ✏️ change something on VK — they post, edit, delete or join on
behalf of whoever owns the access token. Each tool also carries MCP annotations
(readOnlyHint, destructiveHint), so a client can auto-approve lookups while
still asking before a post is edited or deleted.
The model sees only the tools your token reaches. On start the server asks VK
which token it holds — community, user, VK ID or service key — and leaves out
the tools VK would refuse it, so the model does not discover the limits one
error at a time. vk_token_info says which token it is and, for each tool
left out, what would open it. With no token, or when VK cannot tell, every
tool is listed.
Users
Wall
Groups
Photos
Stories
Community messages
Need a community token with the messages right, and messages switched on in
the community settings. VK lets a community write only to people who wrote to
it first or allowed its messages.
Community events
VK refuses a community token comments, likes and the wall, but sends them as
events to a community that listens. Call vk_events_listen once: it turns on
the community's Long Poll and the event types if they are off — leaving the API
version alone when another bot already reads it — and starts receiving. VK
keeps no history: you see what happens from that moment on, while the server
runs. Deleting comments stays closed to a community token.
Other
Prompts
Prompts appear in your client as ready-made workflows — pick one, fill in the community, and the model knows which tools to use.
Like the tools, the prompt list follows the token: a prompt is offered only
when the token reaches the tools it relies on, and publish_post leaves out the
steps (reading the wall, uploading the image) the token cannot take.
Usage Examples
Once configured, you can ask Claude:
- "Get information about Pavel Durov's VK profile"
- "Show me the latest 5 posts from the VK official community"
- "Post 'Hello World!' on my wall"
- "Get the list of communities I'm a member of"
- "Show my newsfeed"
Example Conversation
A real exchange — the numbers below came back from VK while this was written.
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.
The model gets each of those numbers as typed fields rather than text it has to parse, because every tool declares an output schema.
Changelog
See CHANGELOG.md.
Testing
Run the test suite:
npm test
Run tests with coverage:
npm run test:coverage
API Reference
This server wraps VK API v5.199. For detailed parameter documentation, see:
Security Notes
- Never share your access token
- The
offlinescope provides a non-expiring token - Review permissions before authorizing
- For production, consider using a service token
Contributing
Contributions are welcome! Please read the Contributing Guidelines first.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
License
MIT © 2026 bulatko
