VK MCP Server

VK MCP 服务

适用于 VKontakte（VK）的模型上下文协议（MCP）服务——俄罗斯及独联体国家最大的社交网络。

此服务允许 AI 助手（Claude、Cursor、Windsurf、VS Code 等）通过标准化的 MCP 接口与 VK 交互。

功能

• 根据官方架构自动生成 180 多个 VK API 工具（使用 VK_MCP_MODE=all 可启用完整工具集；默认设置仅开放较小的子集）——用户、动态、群组、好友、照片、视频、消息、市场、统计、故事、投票等
• 根据 VK API 架构自动生成——始终与官方 API 保持同步
• 读／写／资金模式过滤——限制 AI 仅执行读取操作、允许非财务写入操作，或启用财务敏感方法
• 分区过滤——包含或排除特定 API 分区（例如，禁用 ads、secure）
• 支持 .env——从环境文件加载令牌，供本地开发使用
• VK 上传 API 辅助工具——为媒体工作流提供上传服务器和保存方法
• 基于 ESM——现代 Node.js 模块系统
• 支持多种传输方式——stdio（适用于 Claude Desktop／Cursor）、Streamable HTTP 和 SSE（适用于 Grok 等远程 MCP 客户端）

先决条件

• Node.js ≥ 18
• 具有所需权限的 VK 访问令牌

安装

选项 1：使用 npx 运行（无需安装）

npx full-vk-mcp

选项 2：全局安装

npm install -g full-vk-mcp
full-vk-mcp

选项 3：从 GitHub 克隆

git clone https://github.com/ssm82/full-vk-mcp.git
cd full-vk-mcp
npm install
node src/index.js

首次运行时会自动下载 VK API 架构。无需手动操作。

配置

1. VK 访问令牌

在项目根目录中创建 .env 文件：

VK_ACCESS_TOKEN=your_vk_token_here

或者从以下位置获取令牌：

• vkhost.github.io——快速令牌生成器
• VK Dev——官方开发者门户

所需权限取决于你的使用场景：

• wall——发布和读取动态
• photos——上传照片
• groups——管理社群
• friends、messages、market、stats——按需设置

**安全提示：**切勿将令牌提交到 git。.env 文件已列入 .gitignore。

2. 选择配置预设（推荐）

无需手动配置分区和方法，可通过 VK_MCP_PROFILE 使用内置配置预设：

VK_MCP_PROFILE=minimal npx full-vk-mcp

配置预设	模式	描述	警告
minimal	读取	基本读取方法	安全
social	读取	用户、好友及其他功能	安全
content_read	读取	约 25 种内容查看方法	安全
content_publish	全部	约 20 种内容创建方法	可以发布内容
community_manager	全部	动态、论坛、群组管理	可以修改社群
messenger	全部	消息及用户信息	需要 messages 权限范围
analytics	读取	统计、动态、群组洞察	安全
money	资金	允许使用资金模式过滤器允许的所有财务敏感方法	财务敏感
ads	资金	广告 API 及辅助方法	可能产生费用
market	资金	VK 市场及上传辅助工具	可以修改商店
commerce	资金	市场、订单、商店、礼物、donut	财务敏感
search	读取	约 10 种搜索方法	安全
full_read	读取	除 ads／secure 外的所有读取方法	安全
full	全部	所有 VK API 方法	仅用于开发

可通过环境变量扩展配置预设：

VK_MCP_PROFILE=social VK_MCP_INCLUDE_SECTIONS=wall npx full-vk-mcp

**环境变量扩展配置预设：**列表类型变量（分区、方法、排除项）会与配置预设合并；标量 mode 会被环境变量覆盖。

3. MCP 客户端设置

VS Code（搭配 Copilot／Claude 等）

创建 .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
    }
  ]
}

若要从克隆的仓库进行本地开发，请使用：

{
  "command": "node",
  "args": ["/absolute/path/to/full-vk-mcp/src/index.js"]
}

Cursor

创建 .cursor/mcp.json：

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

Claude Desktop

编辑 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"
      }
    }
  }
}

从克隆的代码仓库进行本地开发时，请使用：

{
  "command": "node",
  "args": ["/absolute/path/to/full-vk-mcp/src/index.js"]
}

Windsurf / 其他 MCP 客户端

使用 stdio 传输，并通过环境变量提供 VK_ACCESS_TOKEN。

4. 传输模式

默认情况下，服务使用 stdio 传输，为本地 MCP 客户端提供服务。若要启用远程连接，请切换为 HTTP：

VK_MCP_TRANSPORT	用途
stdio (默认)	Claude Desktop、Cursor、VS Code、Windsurf
http	Grok、ChatGPT、远程 MCP 客户端
sse	与 http 相同（同时启用两个端点）

# HTTP mode for remote clients
VK_ACCESS_TOKEN=your_token VK_MCP_TRANSPORT=http npx full-vk-mcp

环境变量

变量	默认值	说明
VK_ACCESS_TOKEN	(必需)	你的 VK API 访问令牌
VK_MCP_PROFILE	—	内置配置名称（minimal、social、full 等）
VK_MCP_MODE	read	read — 只读；write — 非金融类写入；money — 金融敏感操作；all — 所有操作
VK_MCP_INCLUDE_SECTIONS	—	以逗号分隔的 API 分区白名单。未指定配置时，将使用安全子集（users、groups、wall、friends、photos）
VK_MCP_EXCLUDE_SECTIONS	ads,secure,market,orders,store,gifts,donut,votes (未指定配置 / 未显式指定包含项时)	以逗号分隔的 API 分区黑名单。设置 VK_MCP_INCLUDE_SECTIONS 或 VK_MCP_INCLUDE_METHODS 时将跳过此项
VK_MCP_INCLUDE_METHODS	—	以逗号分隔的方法白名单（例如：users.get,wall.get）
VK_MCP_EXCLUDE_METHODS	—	以逗号分隔的方法黑名单
VK_MCP_MAX_TOOLS	—	限制公开的工具数量
VK_MCP_TRANSPORT	stdio	传输类型：stdio、http 或 sse
VK_MCP_PORT	3000	HTTP 端口（对于 Render 等 PaaS，回退使用 $PORT）
VK_MCP_HOST	127.0.0.1	绑定地址。公网上的主机请使用 0.0.0.0
VK_MCP_AUTH_TOKEN	—	HTTP 传输身份验证使用的 Bearer 令牌（绑定到非环回地址时必需）

模式过滤

服务会自动将每个 VK API 方法归类到相应的风险级别：

模式	说明	分区
read	只读方法	安全子集：users、groups、wall、friends、photos
write	读取和非金融类写入	可修改你的账户（发布、编辑、删除、发送等）
money	仅限金融敏感操作	ads、market、orders、store、gifts、donut、votes、部分 secure.*
all	所有操作	读取 + 写入 + 金融操作 — 无限制

• 读取方法 — get*、search*、is*、are*、check*、resolve*、find*、count*、lookup*、list*
• 写入方法 — 其他所有方法（发布、编辑、删除、发送等）
• 金融方法 — 金融分区中的任何方法，或明确标记的方法（secure.getAppBalance 等）

使用 VK_MCP_MODE=read 可防止 AI 对你的 VK 账户进行任何更改。 需要广告、市场或支付相关工具时，请使用 VK_MCP_MODE=money。

本地运行

使用 npm/npx：

VK_ACCESS_TOKEN=your_token npx full-vk-mcp

使用克隆的代码仓库：

# 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 模式

# 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

测试 HTTP 端点

# Health check
curl http://127.0.0.1:3000/health

若要完整测试 MCP 协议，请使用 MCP Inspector：

npx @modelcontextprotocol/inspector

然后选择：

Transport: Streamable HTTP
URL: http://127.0.0.1:3000/mcp

Streamable HTTP 基于会话。只能在发送 initialize 请求后，并携带返回的 Mcp-Session-Id 标头，才能发送原始的 tools/list 请求。

在 Inspector 界面中选择 Streamable HTTP，并输入 http://127.0.0.1:3000/mcp。

可用工具（按类别）

类别	示例	数量
墙	vk_wall_get、vk_wall_post、vk_wall_edit、vk_wall_delete、vk_wall_search	10+
用户	vk_users_get、vk_users_search、vk_users_get_followers	5+
群组	vk_groups_get、vk_groups_get_members、vk_groups_search、vk_groups_join	20+
照片	vk_photos_get、vk_photos_get_upload_server、vk_photos_save	15+
视频	vk_video_get、vk_video_search、vk_video_save	10+
消息	vk_messages_get_history、vk_messages_get_conversations、vk_messages_send	20+
好友	vk_friends_get、vk_friends_get_online、vk_friends_add	10+
市场	vk_market_get、vk_market_search、vk_market_get_orders	10+
故事	vk_stories_get、vk_stories_get_upload_server	5+
投票	vk_polls_create、vk_polls_get_by_id、vk_polls_add_vote	5+
统计数据	vk_stats_get、vk_stats_get_post_reach	2+
广告	vk_ads_get_campaigns、vk_ads_get_ads、vk_ads_get_statistics	15+
+ 60 个其他板块	文档、笔记、论坛、收藏、通知、页面、存储等	—

总计： 根据官方 VK API 架构自动生成了 180+ 个工具。

示例

获取你的墙帖

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

部署

适用于 Render、Railway、Fly.io 或类似的 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 说明： Render 通过 $PORT 环境变量提供端口。如果未设置 VK_MCP_PORT，服务会自动使用该端口。

开发

# 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

注意： 已发布的 npm 包仅包含运行时文件（src/、README.md、LICENSE、server.json）。测试和开发文件保留在 GitHub 仓库中。

VK API 架构

为保持轻量，本仓库不包含 VK API 架构。首次运行时（启动服务或运行测试），会从官方 VK 仓库自动下载：

https://github.com/VKCOM/vk-api-schema

架构会保存到项目根目录下的 vk-api-schema/，并缓存以供后续运行使用。

更新架构

要获取最新的 VK API 变更，请删除缓存文件夹并重启：

rm -rf vk-api-schema/
node src/index.js  # schema will be re-downloaded automatically

安全

• 令牌存储： 使用 .env 或 MCP 客户端的安全环境变量。切勿提交令牌。
• 最小权限： 如果 AI 只需读取数据，请使用 VK_MCP_MODE=read。
• 板块筛选： 如果不需要，请排除 ads、secure 等敏感板块。
• HTTP 模式安全： 默认情况下，HTTP 仅绑定到 127.0.0.1。如果绑定到 0.0.0.0（公网），则必须设置 VK_MCP_AUTH_TOKEN，否则服务将拒绝启动。在生产环境中始终使用 HTTPS。

故障排除

问题	解决方案
VK_ACCESS_TOKEN is required	创建 .env 文件或设置环境变量
Unknown tool	检查方法名称是否使用 snake_case（vk_wall_get，而不是 vk.wall.get）
Access denied	你的令牌缺少所需的 VK 权限范围
工具过多	使用 VK_MCP_INCLUDE_SECTIONS 或 VK_MCP_MODE=read 进行筛选
HTTP Not Acceptable	添加请求头 Accept: application/json, text/event-stream
HTTP VK_MCP_AUTH_TOKEN is required	绑定到 0.0.0.0 时设置身份验证令牌

许可证

MIT

贡献

欢迎提交拉取请求！请先创建 issue，讨论重大变更。

---

为 Model Context Protocol 生态系统打造