vk-community-mcp

MCP server for managing VKontakte communities via Claude Code and other MCP-compatible AI assistants. Covers wall posts, photo albums, market products, community settings, stats, and monitoring — 28 tools total.

Installation

{
  "vk-community": {
    "command": "npx",
    "args": ["-y", "vk-community-mcp"],
    "env": {
      "VK_TOKEN": "${VK_TOKEN}",
      "VK_DEFAULT_GROUP_ID": "YOUR_GROUP_ID"
    }
  }
}

Add this to your .mcp.json in the project root. VK_TOKEN is read from ~/.secrets/secrets.env via the variable substitution mechanism.

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | VK_TOKEN | yes | — | User access token with admin rights on target communities. See section below for how to obtain. | | VK_DEFAULT_GROUP_ID | no | — | Numeric community id used when tool group_id arg is not provided. Recommended for per-brand launchers. If not set, every community-scoped tool requires explicit group_id. | | VK_API_VERSION | no | 5.199 | Override VK API version |

Getting a User Access Token (Kate Mobile flow)

Disclaimer: This method uses the Kate Mobile OAuth client_id (2685278) to generate a user access token with extended scope. This is technically a "gray zone" under VK's Terms of Service — VK does not explicitly permit but widely tolerates this approach, which is used by major SMM services (Senler, SMMplanner, Postmypost). Use at your own risk. For production public services, obtain an official VK ID app via [email protected].

1. Open this URL in a browser where you are logged in to VK as the group admin:

   https://oauth.vk.com/authorize?client_id=2685278&scope=wall,photos,manage,stories,market,docs,video,offline&redirect_uri=https://oauth.vk.com/blank.html&display=page&response_type=token

2. Authorize the app.
3. Copy the access_token value from the redirect URL fragment (#access_token=vk1.a.xxx...).
4. The token is lifetime-unlimited (expires_in=0) due to the offline scope.

Alternatively use vkhost.github.io to generate the OAuth URL visually.

Rate Limits

• 3 requests/second per user token (official VK limit). MCP does not throttle internally — the calling LLM must pace requests.
• ~30–50 wall posts per day across all communities (soft anti-spam limit; VK error 9 "flood control" if exceeded).
• ~250 photo uploads/minute per token.
• Captcha (error 14): VK may require captcha for write operations if it detects bot-like activity. Tools return VkCaptchaError with sid and img_url. Show the image to the user, get the solution, then retry the same tool with captcha_sid and captcha_key params.

Tools

All tools that operate on a community accept an optional group_id parameter to override the default community set by VK_DEFAULT_GROUP_ID.

Group Settings

| Tool | Description | |---|---| | vk_group_get | Get full community info (name, description, members, contacts, settings) | | vk_group_edit | Edit community settings (title, description, website, wall mode, market, age limits) |

Wall

| Tool | Description | |---|---| | vk_wall_post | Publish or schedule a post. Supports attachments, geo-tags, scheduled posting, idempotency key | | vk_wall_edit | Edit an existing post (replaces message and/or attachments) | | vk_wall_delete | Soft-delete a post | | vk_wall_get | Get recent posts (filter: all/owner/others/suggests/postponed) | | vk_wall_get_by_id | Get specific posts by id (supports short form like '12345') | | vk_wall_pin | Pin a post to the top of the wall | | vk_wall_unpin | Unpin the currently pinned post |

Photos

| Tool | Description | |---|---| | vk_set_cover | Set community cover photo from local file (1920x768 recommended) | | vk_set_avatar | Set community avatar from local file (1024x1024 recommended) | | vk_upload_wall_photo | Upload photo for wall post, returns ready attachment string | | vk_upload_album_photo | Upload photo to a specific album |

Photo Albums

| Tool | Description | |---|---| | vk_album_create | Create a new photo album | | vk_album_edit | Edit album title/description/permissions | | vk_album_list | List all albums (excludes system albums by default) | | vk_album_photos | List photos in an album (supports system albums: 'wall', 'profile', 'saved') |

Market / Shop

| Tool | Description | |---|---| | vk_product_add | Add a product to the shop (requires uploaded photo and valid category_id) | | vk_product_edit | Edit product fields; use deleted=true to archive | | vk_upload_product_photo | Upload product photo, returns id for use as main_photo_id | | vk_market_get | List products (filter by album/category, date range, disabled) |

Statistics

| Tool | Description | |---|---| | vk_stats_get | Aggregated community stats (visits, reach, demographics) by day/week/month | | vk_post_reach | Reach statistics for specific wall posts (accepts comma-separated post ids) |

Monitoring

| Tool | Description | |---|---| | vk_mentions_get | Posts/comments where this community is mentioned | | vk_news_search | Search all of VK newsfeed for a query (brand monitoring, competitor research) |

Utilities

| Tool | Description | |---|---| | vk_resolve_screen_name | Resolve VK short name (e.g. 'durov') to numeric id and type | | vk_short_link | Create vk.cc short link with click tracking |

Diagnostics

| Tool | Description | |---|---| | vk_check_token_scope | Check which permissions (wall, photos, manage, market…) the current token has |

Typical Workflow: Posting with Photo

1. vk_upload_wall_photo({ local_path: "/tmp/photo.jpg" })
   → returns { ..., attachment: "photo-123456789_12345" }

2. vk_wall_post({ message: "New collection!", attachments: "photo-123456789_12345" })
   → returns { post_id: 67890 }

Captcha Workflow

1. vk_wall_post({ message: "..." })
   → throws VkCaptchaError: { sid: "xxx", img_url: "https://..." }

2. User solves captcha at img_url, reads the text

3. vk_wall_post({ message: "...", captcha_sid: "xxx", captcha_key: "solved_text" })
   → returns { post_id: ... }

Multi-Community Usage

The same MCP process can manage all communities where the token user is an admin. Use group_id override:

vk_wall_post({ group_id: 111111111, message: "Post for Brand A community" })
vk_wall_post({ group_id: 222222222, message: "Post for Brand B community" })

Or run separate launchers with different VK_DEFAULT_GROUP_ID per brand.

License

MIT