VK MCP Server

Model Context Protocol (MCP) server for VK (VKontakte) social network API

Enables AI assistants like Claude to interact with VK through a standardized interface.

Walls, communities and profiles on a host that supports MCP Apps. The model gets the same structured data either way — this is what the person sees.

Features

• 19 tools across users, walls, communities, photos, likes and statistics
• Read and write: search and read freely; posting, editing and deleting are marked as write operations so your client can ask first
• 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
• 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. --check names which one you hold and probes what it can actually do, --login walks the VK ID flow for the reading kind, and every VK error carries the fix rather than the code alone
• Tested: 84 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

For anything beyond reading public pages, you need a community token. Open a community you manage → Manage → API usage → Access tokens → Create token, ticking wall and photos. Three clicks, no app, never expires, tied to no browser or IP — and it is the only kind VK still lets post, edit or upload.

For public reads alone, either of these does:

npx vk-mcp-server --login <YOUR_APP_ID>   # sign in as yourself

…or the service key from any app page.

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.

Users

Wall

Groups

Photos

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.

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:

• VK API Methods
• VK API Objects

Security Notes

• Never share your access token
• The offline scope 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.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT © 2026 bulatko

Links

• npm Package
• MCP Registry
• VK API Documentation
• Model Context Protocol

Made with ❤️ for the MCP ecosystem