# bulatko/vk-mcp-server [Health: Active]

**Category:** 🌐 Social Media  
**Repository:** https://github.com/bulatko/vk-mcp-server  
**GitHub Stars:** 19  
**npm Downloads (last month):** 873  
**Views:** 10  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/bulatko-vk-mcp-server

## Description
MCP server for VK (VKontakte) social network API. Access users, walls, groups, friends, newsfeed, photos, and community stats.

## Tools
Capabilities this server exposes over MCP:

- **vk_users_get** — Look up VK users by numeric ID or short name (e.g. durov). Use this to resolve a name to an ID before calling other tools, or to check whether a profile is closed.
- **vk_users_search** — Find VK users by name, optionally narrowed by city, country, sex or age. Returns matches with a total count; page through them with offset.
- **vk_wall_get** — Read posts from a user or community wall, newest first. Pass domain for a short address (durov) or owner_id for a numeric one — negative for a community, positive for a person. Each post carries its likes, reposts, comments and views.
- **vk_wall_post** — Publish a post on a wall. Under a community token, leave owner_id out and the post goes on that community's wall. Otherwise, to post in a community, set owner_id to the community ID with a minus sign (-123) and from_group true, or it appears as your personal post on the community wall. Attach media with the attachment string that vk_photos_upload_wall returns. Returns the new post_id.
- **vk_wall_create_comment** — Add a comment to a post. owner_id is negative for a community. Returns the new comment_id.
- **vk_wall_get_by_id** — Fetch particular posts by their full IDs in {owner_id}_{post_id} form, e.g. -1_340393. Use it to re-read a post you already know about, such as one you just published.
- **vk_wall_edit** — Replace the text or attachments of an existing post. owner_id is negative for a community. Editing overwrites the previous content, so pass the full new text rather than an addition.
- **vk_wall_delete** — Delete a post from a wall. owner_id is negative for a community. This cannot be undone.
- **vk_photos_upload_wall** — Upload a photo so it can be attached to a post. Takes a URL or a local file path, runs VK's three-step upload, and returns an attachment string like photo-1_2 to pass to vk_wall_post or vk_wall_edit. group_id is positive here, without the minus sign. Needs a full user token: VK refuses a community token here (error 27), and has no other way for one to attach a photo to a post.
- **vk_stories_post_photo** — Publish a photo story on VK (three-step upload: get upload server, upload the photo, save). Posts a personal story, or a community one when group_id is set.
- **vk_stories_post_video** — Publish a video story on VK (three-step upload: get upload server, upload the video, save). Posts a personal story, or a community one when group_id is set.
- **vk_messages_get_conversations** — List the conversations in your community's inbox, newest first, with the last message of each and the names of the people in them. Use filter "unread" to see what is waiting for a reply. Needs a community token with the messages right.
- **vk_messages_get_history** — Read the messages of one conversation in your community's inbox, newest first. peer_id is the person's user ID, as vk_messages_get_conversations shows it. Needs a community token with the messages right.
- **vk_messages_send** — Send a message from your community to a person. VK only delivers to people who have written to the community or allowed it to message them. This reaches a real person: show the user the text before sending. Returns the new message_id.
- **vk_messages_mark_as_read** — Mark every message in one conversation of your community's inbox as read, e.g. after answering it.
- **vk_events_listen** — Start receiving what happens in your community as it happens: new comments with their text and ID (so you can answer them with vk_wall_create_comment), likes, new posts and reposts, people joining and leaving, messages. Turns on the community's Long Poll and the event types if they are off. VK keeps no history: only events from now on are seen, while this server runs. Read them with vk_events_get.
- **vk_events_get** — Read the community events received since vk_events_listen, oldest first. Pass the returned cursor as after next time to get only new ones. With wait (up to 25 seconds) it holds until something arrives — call it in a loop to follow the community, e.g. to answer each new comment.
- **vk_groups_search** — Find communities by keyword, optionally narrowed by type, country, city or sort order. Returns matches with a total count.
- **vk_groups_get_members** — List the members of a community. Returns bare user IDs unless you ask for fields, in which case it returns profiles. Many communities hide their member list, which comes back as an access error rather than an empty list.
- **vk_groups_join** — Join a community as the token owner, or send a join request if it is closed. group_id is positive here, without the minus sign.
- **vk_groups_get** — List the communities the token owner belongs to. Needs a user token — a community or service token cannot answer this.
- **vk_groups_get_by_id** — Look up communities by numeric ID or short name (e.g. apiclub). Use it to resolve a name to an ID, or to read the description, member count and type before deciding what to do with it.
- **vk_friends_get** — List a user's friends. Returns bare IDs unless you ask for fields. Needs a user token, and only works for profiles that expose their friend list.
- **vk_newsfeed_get** — Read the token owner's own newsfeed. Needs a user token — this is the feed of the account the token belongs to, not a public one.
- **vk_stats_get** — Read a community's statistics by period: reach, visitors and activity. The token owner must be an administrator of that community, otherwise VK denies access.
- **vk_likes_get** — List the users who liked or reacted to an object — a post, comment, photo or video — with counts per reaction. owner_id is negative for a community; item_id is the post or object ID.
- **vk_photos_get** — List photos from an album. album_id accepts wall, profile or saved as well as a numeric album ID. owner_id is negative for a community.
- **vk_token_info** — Say which VK token the server holds — a community token, a user token, a VK ID sign-in token or an app service key — which community it acts as and with which rights, which tools work with it, and for each tool that does not, what would make it work. Call it when unsure what you can do in VK, or before telling the user something cannot be done.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "vk-mcp-server": {
    "command": "npx",
    "args": ["-y","vk-mcp-server"],
    "env": {
      "VK_ACCESS_TOKEN": "",
      "VK_TIMEOUT_MS": "",
      "VK_API_BASE": ""
    }
  }
}
```

**Requires environment variables:** `VK_ACCESS_TOKEN`, `VK_TIMEOUT_MS`, `VK_API_BASE` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What bulatko/vk-mcp-server MCP server does

The bulatko/vk-mcp-server MCP server connects an MCP-compatible client to VKontakte’s API. It provides 19 tools covering user lookup and search, wall reading and publishing, comments, post editing and deletion, community discovery and membership, friend lists, the token owner’s newsfeed, photo uploads and album browsing, likes, and community statistics.

The read tools can resolve users or communities by numeric ID or short name, inspect profile or community details, search by filters, and retrieve paginated results. Wall responses include engagement counters such as likes, reposts, comments, and views. Write operations include publishing posts, adding comments, editing posts, deleting posts, and uploading photos for later attachment.

## How it works

The server translates MCP tool calls into VK API requests and returns structured, typed results. List operations report match counts and continuation offsets, allowing a client to request additional pages instead of treating the first response as complete. Prompts are also included for workflows such as community digests, engagement reports, audience snapshots, and community searches.

VK access depends on the token type and the account or community behind it. User tokens are needed for a user’s communities, friends, and personal newsfeed. Community statistics require the token owner to administer the target community. Posting, editing, and photo uploads require a community token with the relevant permissions. Public profile, wall, and community reads can use a service token or a token obtained through the VK ID login flow, but that login token does not provide the broader operations.

Hosts that support MCP Apps can render walls, communities, and profiles as cards. Other MCP clients still receive the same structured tool data without those visual renderings.

## Setup and configuration

Install and run the package with `npx -y vk-mcp-server`. MCP client configuration supplies the access token through `VK_ACCESS_TOKEN`. The server can start and expose its tools without a token, but tool calls require one. The repository documents configurations for Claude Desktop and Claude Code, and also provides a one-click installation path for VS Code.

`VK_TIMEOUT_MS` controls the request timeout and defaults to 30,000 milliseconds. `VK_API_BASE` can replace the default VK API endpoint with a mirror or proxy. The `--check` option identifies the token type and tests which operations it can reach without invoking write methods. The `--login <APP_ID>` option starts the VK ID sign-in flow for a reading token.

## Tools and capabilities

- Resolve users and communities by ID or short name.
- Search users and communities with filters and pagination.
- Read, publish, edit, comment on, and delete wall posts.
- Upload photos for wall attachments and list album photos.
- List community members, joined communities, friends, and the token owner’s newsfeed.
- Read reactions and community reach, visitor, and activity statistics.

## Limitations and notes

VK’s permissions are not uniform across token types. A service token cannot call user methods, private profiles may deny access, and communities can hide their member lists. Friend retrieval only works when the target profile exposes its friends. Statistics are restricted to community administrators.

User tokens are rate-limited to a few requests per second. The server retries rate-limit responses with backoff up to three times, and it reports timeout, captcha, HTTP, and VK API errors with explanatory messages. Deleting a wall post is irreversible, while editing replaces the existing text or attachments rather than appending to them.

The bulatko/vk-mcp-server MCP server is therefore best suited to VK workflows where the required token permissions are known in advance. Use numeric negative owner IDs for community walls, positive IDs for personal walls, and positive group IDs when uploading community photos.

_Full upstream README: https://allmcps.com/mcp/bulatko-vk-mcp-server/readme_

