VK MCP Server

<p align="center"> <img src="https://upload.wikimedia.org/wikipedia/commons/2/21/VK.com-logo.svg" width="100" alt="VK Logo"> </p> <p align="center"> <a href="https://www.npmjs.com/package/vk-mcp-server"><img src="https://img.shields.io/npm/v/vk-mcp-server.svg" alt="npm version"></a> <a href="https://www.npmjs.com/package/vk-mcp-server"><img src="https://img.shields.io/npm/dm/vk-mcp-server.svg" alt="npm downloads"></a> <a href="https://github.com/bulatko/vk-mcp-server/actions"><img src="https://github.com/bulatko/vk-mcp-server/workflows/CI/badge.svg" alt="CI"></a> <a href="https://github.com/bulatko/vk-mcp-server/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/vk-mcp-server.svg" alt="license"></a> </p> <p align="center"> <strong>Model Context Protocol (MCP) server for VK (VKontakte) social network API</strong> </p> <p align="center"> Enables AI assistants like Claude to interact with VK through a standardized interface. </p> <p align="center"> <a href="https://glama.ai/mcp/servers/bulatko/vk-mcp-server"> <img width="380" height="200" src="https://glama.ai/mcp/servers/bulatko/vk-mcp-server/badge" alt="vk-mcp-server MCP server" /> </a> </p>

---

<p align="center"> <img src="docs/img/wall-card.jpg" width="420" alt="A VK wall rendered as a card in the chat: posts with their photos, clip previews and counters" /> </p> <p align="center"> <img src="docs/img/entity-cards.jpg" width="720" alt="A community and a profile rendered as cards: banner, avatar, size and description on one; avatar, location and following on the other" /> </p> <p align="center"> <em>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.</em> </p>

---

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

| Variable | Required | Default | Purpose | |----------|----------|---------|---------| | VK_ACCESS_TOKEN | for tool calls | — | VK API access token. The server starts and lists its tools without one; calling a tool then returns an error saying so | | VK_TIMEOUT_MS | no | 30000 | Abort a VK request that hangs longer than this | | VK_API_BASE | no | https://api.vk.com/method | Point the server at an API mirror or proxy |

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

| Command | What it does | |---------|--------------| | npx vk-mcp-server | Runs the MCP server (this is what your client calls) | | npx vk-mcp-server --login <APP_ID> | Gets a token through VK ID in your browser | | npx vk-mcp-server --check | Reports what your token is and which tools it can use | | npx vk-mcp-server --help | Lists the commands and environment variables |

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:

| What you see | What it means | |--------------|---------------| | error 8: Application is blocked | The VK app that issued the token is blocked. Every token from it fails this way, however valid the token looks. Create your own app and issue a fresh token. | | error 5: User authorization failed | The token expired or was revoked — run --login again. | | error 1051 or error 28 | A service token cannot call user methods. Use a user or community token. | | error 15: Access denied | The data is restricted — a private profile, or a community that hides its members. | | error 5 with subcode 1130 | VK bound the token to the IP that authorised it, and the server is on a different one. Common when the server runs on a VPS but you signed in from your laptop. Get the token on the machine that runs the server, or use a community token. | | Security Error when authorising | The old implicit OAuth flow. Use --login, which does the current VK ID flow. | | No VK token configured on every tool | The server is running but your client never passed VK_ACCESS_TOKEN to it. Check the env block in your client config — a token in your shell does not reach a server the client spawns itself. |

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

| Tool | Description | |------|-------------| | vk_users_get | Get user profiles by IDs or screen names | | vk_users_search | Search users by name, city, age and other criteria |

Wall

| Tool | Description | |------|-------------| | vk_wall_get | Get posts from user/community wall | | vk_wall_get_by_id | Get specific posts by {owner_id}_{post_id} | | vk_wall_post | ✏️ Publish a new post | | vk_wall_edit | ✏️ Edit an existing post | | vk_wall_delete | ✏️ Delete a post | | vk_wall_create_comment | ✏️ Add comment to a post |

Groups

| Tool | Description | |------|-------------| | vk_groups_get | Get user's communities list | | vk_groups_get_by_id | Get community info by ID | | vk_groups_search | Search communities by name and criteria | | vk_groups_get_members | Get community members | | vk_groups_join | ✏️ Join a community or request to join |

Photos

| Tool | Description | |------|-------------| | vk_photos_get | Get photos from albums | | vk_photos_upload_wall | ✏️ Upload a photo and get an attachment string for vk_wall_post |

Other

| Tool | Description | |------|-------------| | vk_friends_get | Get user's friends list | | vk_newsfeed_get | Get user's newsfeed | | vk_likes_get | Get users who liked an object, with reaction counts | | vk_stats_get | Get community statistics (admin only) |

Prompts

Prompts appear in your client as ready-made workflows — pick one, fill in the community, and the model knows which tools to use.

| Prompt | What it does | |--------|--------------| | community_digest | Reads recent posts and summarises themes, standouts and cadence | | engagement_report | Ranks posts by likes and by comments, then explains what the winners share | | audience_snapshot | Samples members and describes the audience by sex, city and activity | | publish_post | Drafts a post in the community's own tone, shows it for approval, publishes it | | find_communities | Searches communities on a topic and compares the candidates |

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