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 port via the $PORT environment variable. The server automatically falls back to it when VK_MCP_PORT is not set.

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

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.

• HTTP mode security: By default, HTTP binds to 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.

Troubleshooting

License

MIT

Contributing

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

Made for the Model Context Protocol ecosystem