Server data from the Official MCP Registry
MCP server for VK API with 180+ tools: users, wall, groups, friends, photos, messages.
MCP server for VK API with 180+ tools: users, wall, groups, friends, photos, messages.
Valid MCP server (1 strong, 1 medium validity signals). No known CVEs in dependencies. Package registry verified. Imported from the Official MCP Registry.
4 files analyzed · 1 issue found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
This plugin requests these system permissions. Most are normal for its category.
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-ssm82-vk-mcp": {
"args": [
"-y",
"full-vk-mcp"
],
"command": "npx"
}
}
}From the project's GitHub README.
Model Context Protocol (MCP) server for VKontakte (VK) — the largest social network in Russia and CIS countries.
This server allows AI assistants (Claude, Cursor, Windsurf, VS Code, etc.) to interact with VK through a standardized MCP interface.
VK_MCP_MODE=all; safe defaults expose a smaller subset) — users, wall, groups, friends, photos, videos, messages, market, stats, stories, polls, and moreads, secure).env support — load token from environment file for local developmentnpx full-vk-mcp
npm install -g full-vk-mcp
full-vk-mcp
git clone https://github.com/ssm82/full-vk-mcp.git
cd full-vk-mcp
npm install
node src/index.js
The VK API schema is downloaded automatically on the first run. No manual steps needed.
Create a .env file in the project root:
VK_ACCESS_TOKEN=your_vk_token_here
Or get a token from:
Required permissions depend on your use case:
wall — posting and reading wallphotos — uploading photosgroups — community managementfriends, messages, market, stats — as neededSecurity: Never commit your token to git. The
.envfile is already in.gitignore.
Instead of manually configuring sections and methods, use a built-in profile via VK_MCP_PROFILE:
VK_MCP_PROFILE=minimal npx full-vk-mcp
| Profile | Mode | Description | Warning |
|---|---|---|---|
minimal | read | Essential read methods | Safe |
social | read | Users, friends + extras | Safe |
content_read | read | ~25 content viewing methods | Safe |
content_publish | all | ~20 content creation methods | Can publish |
community_manager | all | Wall, board, groups management | Can modify communities |
messenger | all | Messages + user info | Requires messages scope |
analytics | read | Stats, wall, groups insights | Safe |
money | money | All financially sensitive methods allowed by money-mode filtering | Financially sensitive |
ads | money | Ads API + helper methods | Can spend money |
market | money | VK Market + upload helpers | Can modify shop |
commerce | money | Market, orders, store, gifts, donut | Financially sensitive |
search | read | ~10 search methods | Safe |
full_read | read | All read methods except ads/secure | Safe |
full | all | All VK API methods | Development only |
Profiles can be extended with environment variables:
VK_MCP_PROFILE=social VK_MCP_INCLUDE_SECTIONS=wall npx full-vk-mcp
Env extends profile: list variables (sections, methods, excludes) are merged with the profile; scalar
modeis overridden by env.
Create .vscode/mcp.json:
{
"servers": {
"vk": {
"type": "stdio",
"command": "npx",
"args": ["-y", "full-vk-mcp"],
"env": {
"VK_ACCESS_TOKEN": "${input:vk-token}",
"VK_MCP_PROFILE": "minimal"
}
}
},
"inputs": [
{
"type": "promptString",
"id": "vk-token",
"description": "VK Access Token",
"password": true
}
]
}
For local development from a cloned repository, use:
{
"command": "node",
"args": ["/absolute/path/to/full-vk-mcp/src/index.js"]
}
Create .cursor/mcp.json:
{
"mcpServers": {
"vk": {
"command": "npx",
"args": ["-y", "full-vk-mcp"],
"env": {
"VK_ACCESS_TOKEN": "your_token",
"VK_MCP_PROFILE": "social"
}
}
}
}
Edit claude_desktop_config.json:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%/Claude/claude_desktop_config.json~/.config/Claude/claude_desktop_config.json{
"mcpServers": {
"vk": {
"command": "npx",
"args": ["-y", "full-vk-mcp"],
"env": {
"VK_ACCESS_TOKEN": "your_token",
"VK_MCP_PROFILE": "minimal"
}
}
}
}
For local development from a cloned repository, use:
{
"command": "node",
"args": ["/absolute/path/to/full-vk-mcp/src/index.js"]
}
Use the stdio transport and provide VK_ACCESS_TOKEN via environment variables.
By default, the server uses stdio transport for local MCP clients. To enable remote connections, switch to HTTP:
VK_MCP_TRANSPORT | Use case |
|---|---|
stdio (default) | Claude Desktop, Cursor, VS Code, Windsurf |
http | Grok, ChatGPT, remote MCP clients |
sse | Same as http (both endpoints enabled) |
# HTTP mode for remote clients
VK_ACCESS_TOKEN=your_token VK_MCP_TRANSPORT=http npx full-vk-mcp
| Variable | Default | Description |
|---|---|---|
VK_ACCESS_TOKEN | (required) | Your VK API access token |
VK_MCP_PROFILE | — | Built-in profile name (minimal, social, full, etc.) |
VK_MCP_MODE | read | read — read-only, write — non-financial writes, money — financially sensitive, all — everything |
VK_MCP_INCLUDE_SECTIONS | — | Comma-separated whitelist of API sections. Without a profile, safe subset (users, groups, wall, friends, photos) is used |
VK_MCP_EXCLUDE_SECTIONS | ads,secure,market,orders,store,gifts,donut,votes (without profile / without explicit includes) | Comma-separated blacklist of API sections. Skipped when VK_MCP_INCLUDE_SECTIONS or VK_MCP_INCLUDE_METHODS is set |
VK_MCP_INCLUDE_METHODS | — | Comma-separated whitelist of methods (e.g., users.get,wall.get) |
VK_MCP_EXCLUDE_METHODS | — | Comma-separated blacklist of methods |
VK_MCP_MAX_TOOLS | — | Limit the number of exposed tools |
VK_MCP_TRANSPORT | stdio | Transport type: stdio, http, or sse |
VK_MCP_PORT | 3000 | HTTP port (falls back to $PORT for PaaS like Render) |
VK_MCP_HOST | 127.0.0.1 | Bind address. Use 0.0.0.0 for public hosts |
VK_MCP_AUTH_TOKEN | — | Bearer token for HTTP transport auth (required when binding to non-loopback) |
The server automatically classifies each VK API method into risk levels:
| Mode | Description | Sections |
|---|---|---|
read | Read-only methods | Safe subset: users, groups, wall, friends, photos |
write | Read + non-financial writes | Can modify your account (post, edit, delete, send, etc.) |
money | Financially sensitive only | ads, market, orders, store, gifts, donut, votes, selected secure.* |
all | Everything | Read + write + money — no restrictions |
get*, search*, is*, are*, check*, resolve*, find*, count*, lookup*, list*secure.getAppBalance, etc.)Use VK_MCP_MODE=read to prevent the AI from making any changes to your VK account.
Use VK_MCP_MODE=money when you need ads, market, or payment-related tools.
With npm/npx:
VK_ACCESS_TOKEN=your_token npx full-vk-mcp
With a cloned repository:
# With .env file (recommended for development)
node src/index.js
# Or inline
VK_ACCESS_TOKEN=your_token node src/index.js
# Use a profile
VK_ACCESS_TOKEN=your_token VK_MCP_PROFILE=minimal node src/index.js
# Read-only mode
VK_ACCESS_TOKEN=your_token VK_MCP_MODE=read node src/index.js
# Include only specific sections
VK_ACCESS_TOKEN=your_token VK_MCP_INCLUDE_SECTIONS=users,wall node src/index.js
# Start HTTP server (localhost only, no auth)
VK_ACCESS_TOKEN=your_token VK_MCP_TRANSPORT=http npx full-vk-mcp
# With custom port
VK_MCP_TRANSPORT=http VK_MCP_PORT=8080 npx full-vk-mcp
# Public deploy (auth required)
VK_MCP_TRANSPORT=http VK_MCP_HOST=0.0.0.0 VK_MCP_AUTH_TOKEN=your_secret npx full-vk-mcp
# Health check
curl http://127.0.0.1:3000/health
For full MCP protocol testing, use the MCP Inspector:
npx @modelcontextprotocol/inspector
Then select:
Transport: Streamable HTTP
URL: http://127.0.0.1:3000/mcp
Streamable HTTP is session-based. A raw tools/list request must be sent only after an initialize request and with the returned Mcp-Session-Id header.
In the Inspector UI select Streamable HTTP and enter http://127.0.0.1:3000/mcp.
| Category | Examples | Count |
|---|---|---|
| Wall | vk_wall_get, vk_wall_post, vk_wall_edit, vk_wall_delete, vk_wall_search | 10+ |
| Users | vk_users_get, vk_users_search, vk_users_get_followers | 5+ |
| Groups | vk_groups_get, vk_groups_get_members, vk_groups_search, vk_groups_join | 20+ |
| Photos | vk_photos_get, vk_photos_get_upload_server, vk_photos_save | 15+ |
| Videos | vk_video_get, vk_video_search, vk_video_save | 10+ |
| Messages | vk_messages_get_history, vk_messages_get_conversations, vk_messages_send | 20+ |
| Friends | vk_friends_get, vk_friends_get_online, vk_friends_add | 10+ |
| Market | vk_market_get, vk_market_search, vk_market_get_orders | 10+ |
| Stories | vk_stories_get, vk_stories_get_upload_server | 5+ |
| Polls | vk_polls_create, vk_polls_get_by_id, vk_polls_add_vote | 5+ |
| Stats | vk_stats_get, vk_stats_get_post_reach | 2+ |
| Ads | vk_ads_get_campaigns, vk_ads_get_ads, vk_ads_get_statistics | 15+ |
| + 60 more sections | docs, notes, board, fave, notifications, pages, storage, etc. | — |
Total: 180+ tools auto-generated from the official VK API schema.
Tool: vk_wall_get
Arguments: { "count": 5 }
Tool: vk_users_search
Arguments: { "q": "Ivan Ivanov", "count": 10 }
Tool: vk_groups_get_members
Arguments: { "group_id": "apiclub", "count": 100 }
Tool: vk_polls_create
Arguments: {
"question": "What's your favorite color?",
"add_answers": "[\"Red\", \"Green\", \"Blue\"]"
}
For Render, Railway, Fly.io, or similar PaaS:
# build command
npm install
# start command (when deploying from repository)
node src/index.js
# or when deploying from npm package
npx full-vk-mcp
# environment variables
VK_ACCESS_TOKEN=...
VK_MCP_TRANSPORT=http
VK_MCP_HOST=0.0.0.0
VK_MCP_PORT=3000 # or omit to use $PORT (Render auto-sets it)
VK_MCP_AUTH_TOKEN=... # required for public access
VK_MCP_MODE=read # or your chosen profile/mode
Render note: Render provides the port via the
$PORTenvironment variable. The server automatically falls back to it whenVK_MCP_PORTis not set.
# Run tests (schema downloads automatically on first run)
npm test
# Start the server
node src/index.js
full-vk-mcp/
├── src/
│ ├── index.js # Entry point (transport switching)
│ ├── server-factory.js # MCP server factory
│ ├── http-transport.js # HTTP/SSE transport
│ ├── schema-loader.js # Loads and filters VK API schema
│ ├── tool-registry.js # Builds MCP tools from schema
│ ├── param-converter.js # Converts VK params to JSON Schema
│ ├── profiles.js # Built-in profiles
│ └── vk-client.js # VK API HTTP client
├── vk-api-schema/ # Official VK API schema (JSON) — see note below
├── tests.test.js # Test suite
├── .env # Your token (gitignored)
├── package.json
└── README.md
Note: The published npm package includes runtime files only (
src/,README.md,LICENSE,server.json). Tests and development files are kept in the GitHub repository.
The VK API schema is not included in this repository to keep it lightweight. On the first run (server or tests), it is downloaded automatically from the official VK repository:
https://github.com/VKCOM/vk-api-schema
The schema is saved to vk-api-schema/ in the project root and cached for subsequent runs.
To get the latest VK API changes, delete the cached folder and restart:
rm -rf vk-api-schema/
node src/index.js # schema will be re-downloaded automatically
.env or your MCP client's secure environment variables. Never commit tokens.VK_MCP_MODE=read if the AI only needs to read data.ads, secure if not needed.127.0.0.1 only. If you bind to 0.0.0.0 (public), VK_MCP_AUTH_TOKEN is required — the server will refuse to start without it. Always use HTTPS in production.| Issue | Solution |
|---|---|
VK_ACCESS_TOKEN is required | Create .env file or set the environment variable |
Unknown tool | Check that the method name uses snake_case (vk_wall_get not vk.wall.get) |
Access denied | Your token lacks the required VK permission scope |
| Too many tools | Use VK_MCP_INCLUDE_SECTIONS or VK_MCP_MODE=read to filter |
HTTP Not Acceptable | Add header Accept: application/json, text/event-stream |
HTTP VK_MCP_AUTH_TOKEN is required | Set auth token when binding to 0.0.0.0 |
MIT
Pull requests are welcome! Please open an issue first to discuss major changes.
Made for the Model Context Protocol ecosystem
Be the first to review this server!
by Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
by mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.