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

• Stdio transport — standard MCP transport, no network exposure

Prerequisites

• Node.js ≥ 18

• VK Access Token with required permissions

Installation

# Clone the repository
git clone https://github.com/ssm82/full-vk-mcp.git
cd full-vk-mcp

# Install dependencies
npm install

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 node src/index.js

Profiles can be extended with environment variables:

VK_MCP_PROFILE=social VK_MCP_INCLUDE_SECTIONS=wall node src/index.js

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": "node",
      "args": ["src/index.js"],
      "env": {
        "VK_ACCESS_TOKEN": "${input:vk-token}",
        "VK_MCP_PROFILE": "minimal"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "vk-token",
      "description": "VK Access Token",
      "password": true
    }
  ]
}

Cursor

Create .cursor/mcp.json:

{
  "mcpServers": {
    "vk": {
      "command": "node",
      "args": ["src/index.js"],
      "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": "node",
      "args": ["/absolute/path/to/full-vk-mcp/src/index.js"],
      "env": {
        "VK_ACCESS_TOKEN": "your_token",
        "VK_MCP_PROFILE": "minimal"
      }
    }
  }
}

Windsurf / Other MCP Clients

Use the stdio transport and provide VK_ACCESS_TOKEN via environment variables.

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

CLI Commands

# List all available profiles
node src/index.js --list-profiles

# List tools for a specific profile (no token required)
VK_MCP_PROFILE=minimal node src/index.js --list-tools

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

Development

# Run tests (schema downloads automatically on first run)
npm test

# Start the server
node src/index.js

Project Structure

full-vk-mcp/
├── src/
│   ├── index.js           # MCP server entry point
│   ├── 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
│   └── 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

VK API Schema

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.

Updating the Schema

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

Security

• Token storage: Use .env or your MCP client's secure environment variables. Never commit tokens.

• Least privilege: Use VK_MCP_MODE=read if the AI only needs to read data.

• Section filtering: Exclude sensitive sections like ads, secure if not needed.

• Local execution: The server uses stdio transport — it does not open any network ports.

Troubleshooting

License

MIT

Contributing

Pull requests are welcome! Please open an issue first to discuss major changes.

Made for the Model Context Protocol ecosystem