VK MCP Server

VK MCP Server

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.

Features

• 180+ VK API tools auto-generated from the official schema (full set available with VK_MCP_MODE=all; safe defaults expose a smaller subset) — users, wall, groups, friends, photos, videos, messages, market, stats, stories, polls, and more
• Auto-generated from VK API schema — always up-to-date with the official API
• Read/Write/Money mode filtering — restrict AI to read-only, allow non-financial writes, or enable financially sensitive methods
• Section filtering — include or exclude specific API sections (e.g., disable ads, secure)
• `.env` support — load token from environment file for local development
• VK upload API helpers — exposes upload-server and save methods for media workflows
• ESM-based — modern Node.js module system
• Multiple transports — stdio (for Claude Desktop / Cursor), Streamable HTTP and SSE (for remote MCP clients like Grok)

Prerequisites

• Node.js ≥ 18
• VK Access Token with required permissions

Installation

Option 1: Run with npx (no install)

npx full-vk-mcp

Option 2: Install globally

npm install -g full-vk-mcp

full-vk-mcp

Option 3: Clone from GitHub

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.

Configuration

1. VK Access Token

Create a .env file in the project root:

VK_ACCESS_TOKEN=your_vk_token_here

Or get a token from:

• vkhost.github.io — quick token generator
• VK Dev — official developer portal

Required permissions depend on your use case:

• wall — posting and reading wall
• photos — uploading photos
• groups — community management
• friends, messages, market, stats — as needed

Security: Never commit your token to git. The .env file is already in .gitignore.

2. Choose a Profile (Recommended)

Instead of manually configuring sections and methods, use a built-in profile via VK_MCP_PROFILE:

VK_MCP_PROFILE=minimal npx full-vk-mcp

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 mode is overridden by env.

3. MCP Client Setup

VS Code (with Copilot / Claude / etc.)

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"] }

Cursor

Create .cursor/mcp.json:

{

"mcpServers": { "vk": { "command": "npx", "args": ["-y", "full-vk-mcp"], "env": { "VK_ACCESS_TOKEN": "your_token", "VK_MCP_PROFILE": "social" } } } }

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json
• Linux: ~/.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"] }

Windsurf / Other MCP Clients

Use the stdio transport and provide VK_ACCESS_TOKEN via environment variables.

4. Transport Mode

By default, the server uses stdio transport for local MCP clients. To enable remote connections, switch to HTTP:

# HTTP mode for remote clients

VK_ACCESS_TOKEN=your_token VK_MCP_TRANSPORT=http npx full-vk-mcp

Environment Variables

Mode Filtering

The server automatically classifies each VK API method into risk levels:

• Read methods — get*, search*, is*, are*, check*, resolve*, find*, count*, lookup*, list*
• Write methods — everything else (post, edit, delete, send, etc.)
• Money methods — any method in financial sections or explicitly tagged (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.

Running Locally

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

HTTP Mode

# 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

Test HTTP endpoint

# 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.

Available Tools (by Category)

Total: 180+ tools auto-generated from the official VK API schema.

Examples

Get your wall posts

Tool: vk_wall_get

Arguments: { "count": 5 }

Search for users

Tool: vk_users_search

Arguments: { "q": "Ivan Ivanov", "count": 10 }

Get community members

Tool: vk_groups_get_members

Arguments: { "group_id": "apiclub", "count": 100 }

Create a poll

Tool: vk_polls_create

Arguments: { "question": "What's your favorite color?", "add_answers": "[\"Red\", \"Green\", \"Blue\"]" }

Deployment

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