vk

VK MCP 服务

用于 VK（VKontakte）社交网络 API 的模型上下文协议（MCP）服务

English · Русский · 网站（RU）

让 Claude 等 AI 助手能够通过标准化接口与 VK 交互。

---

在支持 MCP Apps 的宿主中呈现墙、社区和个人资料。无论哪种方式， 模型获得的结构化数据都相同——这里展示的是用户看到的内容。

---

功能

• 25 个工具，涵盖用户、墙、社群、照片、故事、社群消息、点赞和统计数据
• 你的社群收件箱：列出未读对话、阅读并回复。助手以社群身份起草，你审核后发送
• 以社群身份读写：同时使用社群令牌和服务密钥时，助手可以读取墙、个人资料和社群，并以你的社群身份发帖、评论、发布故事和回复消息。写入操作会明确标记，以便你的客户端先征求确认。有些工具（搜索、点赞、统计数据、编辑）需要完整的用户令牌，而 VK 已不再向新应用发放此类令牌——设置指南准确列出了每种令牌的权限范围
• 结构化输出：每个工具都声明了输出架构，因此模型会收到类型化数据，而不是需要从文本中解析的 JSON 块
• 分页信息清晰：列表结果会说明匹配项总数，以及从哪个偏移量继续，因此模型可以翻阅墙上的内容，而不是只停留在前 20 条帖子
• 可视化内容：在支持 MCP Apps 的宿主中——Claude、Claude Desktop、VS Code Copilot、Goose——墙、社群和个人资料会以卡片形式呈现：帖子附带照片和视频片段预览，社群展示横幅和规模，个人资料展示头像和关注状态。其他环境中的行为则完全不变
• 提示词：开箱即用的工作流——社群摘要、互动报告、受众概览、社群搜索、社群收件箱
• 弹性可靠：请求超时、遇到 VK 速率限制时自动退避，以及清晰的验证码和 HTTP 错误提示
• 如实说明令牌权限：VK 有三种令牌，权限范围差异很大。--check 会指出你持有哪种令牌，并探测它实际能做什么；--login 会引导你通过 VK ID 流程获取读取类令牌；每条 VK 错误信息都会提供修复方法，而不只是错误代码
• 经过测试：通过 MCP 协议驱动真实服务端的测试超过 140 项

快速开始

Claude Desktop——一键安装

从发布页面下载最新的 .mcpb 捆绑包并打开。它会安装服务端，通过表单字段索取你的 VK 令牌，并安全存储——无需 Node.js、配置文件或终端。

VS Code——一键安装

VS Code 会提示你输入 VK 令牌，并确保令牌不会写入配置文件。也可以改用终端：

code --add-mcp '{"name":"vk","command":"npx","args":["-y","vk-mcp-server"],"env":{"VK_ACCESS_TOKEN":"your_token"}}'

npm

npx vk-mcp-server

也可以使用 npm install -g vk-mcp-server 进行全局安装。

MCP Registry

也可在官方 MCP Registry 中获取：

io.github.bulatko/vk

获取 VK 访问令牌

要让助手发帖，你需要社区令牌。 打开你管理的社区 → 管理 → API 使用 → 访问令牌 → 创建令牌，勾选 wall、photos、stories、messages 和 manage。点击三次即可，无需应用，不会过期，也不绑定浏览器或 IP。它可以代表社区发帖、评论和发布故事。

再添加一个服务密钥，助手就能读取动态墙。 VK 不允许社区令牌读取动态墙（错误 27）。在 VK 应用的设置页面获取服务密钥，并将其设为 VK_SERVICE_KEY；之后，服务器会使用该密钥执行所有被访问令牌拒绝的读取操作，而写入操作绝不会使用它：

"env": {
  "VK_ACCESS_TOKEN": "vk1.a...community token",
  "VK_SERVICE_KEY": "...service key"
}

截至 2026 年 10 月，根据对实时 API 的检查，VK 为新应用签发的令牌都无法执行这些操作：编辑或删除帖子、上传动态墙照片、读取统计数据、点赞、读取相册、搜索或读取新闻源。VK 仅向完整用户令牌开放这些功能，而现在已不再签发此类令牌。

如果只需读取公开内容，单独使用服务密钥即可（设为 VK_SERVICE_KEY 或 VK_ACCESS_TOKEN），也可以登录你自己的账号：

npx vk-mcp-server --login <YOUR_APP_ID>

花一晚上折腾前，值得先了解这一点： --login 返回的是 VK ID 令牌（vk2.a…），VK 签发它是用于登录，而非调用 API。它可以读取公开个人资料、动态墙和社区信息；无论请求哪些权限范围，发帖、照片、好友、信息流和统计数据的操作都会返回 error 1051。过去可获取完整用户令牌的流程，现在会直接拒绝新创建的应用。npx vk-mcp-server --check 会说明你持有的令牌类型及其可访问的内容。

请使用自己的应用，而不是别处的 App ID：令牌会随签发它的应用失效，而且错误信息不会提示这就是原因。

📖 完整设置指南 — 包含每个步骤的确切界面、各权限范围开放的功能、远程安装方式，以及各种错误的含义。

配置

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "vk": {
      "command": "npx",
      "args": ["-y", "vk-mcp-server"],
      "env": {
        "VK_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}

Claude Code

添加到项目的 .mcp.json：

{
  "mcpServers": {
    "vk": {
      "command": "npx",
      "args": ["-y", "vk-mcp-server"],
      "env": {
        "VK_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}

环境变量

变量	必需	默认值	用途
VK_ACCESS_TOKEN	用于调用工具	—	工具使用的令牌，通常是社区令牌。没有令牌时，服务器仍会启动并列出工具；调用工具时则会返回相应错误
VK_SERVICE_KEY	否	—	VK 应用的服务密钥。使用该密钥执行被访问令牌拒绝的读取操作（例如使用社区令牌时读取动态墙）；绝不用于写入操作。单独使用时也足以读取公开内容
VK_TIMEOUT_MS	否	30000	VK 请求超过此时长仍未完成时，将其中止
VK_API_BASE	否	https://api.vk.com/method	将服务器指向 API 镜像或代理

VK 会将用户令牌的频率限制为每秒几次调用。收到错误 6（请求过多）时，服务器会退避并最多重试三次，然后才放弃，因此短时间内连续调用工具不会直接失败。

命令行

命令	功能
npx vk-mcp-server	运行 MCP 服务（客户端会调用此命令）
npx vk-mcp-server --login <APP_ID>	在浏览器中通过 VK ID 获取令牌
npx vk-mcp-server --check	显示你的令牌类型及其可使用的工具
npx vk-mcp-server --help	列出命令和环境变量

故障排除

从这里开始：

VK_ACCESS_TOKEN=your_token npx vk-mcp-server --check

它会识别你持有的三种令牌类型之一——用户、社区或服务令牌——并探测该令牌实际能访问哪些内容，让你提前了解情况，而不是逐个工具尝试后才发现。它不会调用任何写入方法。

常见情况：

你看到的内容	含义
error 8: Application is blocked	签发该令牌的 VK 应用已被封禁。该应用签发的所有令牌都会以此方式失效，无论令牌看起来多么有效。请创建自己的应用并签发新令牌。
error 5: User authorization failed	令牌未被接受：可能已撤销、删除或被更新的令牌替代，也可能粘贴时带有引号、空格或行尾注释。请确认令牌完整无误；若确认无误，请在令牌的来源处重新创建（社区令牌：Manage → API usage → Access tokens）。--login 只会重新签发 VK ID 令牌，而 VK ID 令牌无法发布内容。
error 27: Group authorization failed	社区令牌请求了 VK 不允许它访问的内容，例如读取墙。设置 VK_SERVICE_KEY 后，读取操作将使用该密钥；编辑、删除和统计功能仍无法使用。
error 1051 或 error 28	VK ID 令牌或服务密钥请求了其无权使用的方法。要发布内容，请使用社区令牌。
error 15: Access denied	数据受到限制，例如私人个人资料，或隐藏成员的社区。
error 5 with subcode 1130	VK 将令牌绑定到了授权该令牌的 IP，而服务所在的 IP 不同。服务运行在 VPS 上、但你从笔记本电脑登录时，常会出现这种情况。请在运行服务的机器上获取令牌，或使用社区令牌。
授权时出现 Security Error	使用了旧版隐式 OAuth 流程。请使用 --login，它会执行当前的 VK ID 流程。
每个工具都显示 No VK token configured	服务正在运行，但客户端从未向它传递 VK_ACCESS_TOKEN。请检查客户端配置中的 env 块——shell 中的令牌不会传递给客户端自行启动的服务。

服务会将这些情况转换成说明处理方法的消息，因此模型通常可以解释如何修复问题，无需你阅读此表。

可用工具

标有 ✏️ 的工具会更改 VK 上的内容——它们会代表访问令牌所有者发布、编辑、删除内容或加入社区。每个工具还带有 MCP 注释（readOnlyHint、destructiveHint），因此客户端可以自动批准查询，同时在编辑或删除帖子前仍会请求确认。

模型只能看到令牌可访问的工具。启动时，服务会询问 VK 当前持有的令牌类型——社区、用户、VK ID 或服务密钥——并省略 VK 会拒绝的工具，这样模型就不必一次次遇到错误才能发现限制。vk_token_info 会说明令牌类型，并针对每个被省略的工具说明如何启用它。没有令牌，或 VK 无法识别令牌时，将列出所有工具。

用户

工具	描述
vk_users_get	根据 ID 或屏幕名称获取用户个人资料
vk_users_search	根据姓名、城市、年龄和其他条件搜索用户

墙

工具	描述
vk_wall_get	获取用户或社区墙上的帖子
vk_wall_get_by_id	根据 {owner_id}_{post_id} 获取指定帖子
vk_wall_post	✏️ 发布新帖子
vk_wall_edit	✏️ 编辑现有帖子
vk_wall_delete	✏️ 删除帖子
vk_wall_create_comment	✏️ 为帖子添加评论

群组

工具	描述
vk_groups_get	获取用户的社区列表
vk_groups_get_by_id	根据 ID 获取社区信息
vk_groups_search	根据名称和条件搜索社区
vk_groups_get_members	获取社区成员
vk_groups_join	✏️ 加入社区或申请加入

照片

工具	描述
vk_photos_get	获取相册中的照片
vk_photos_upload_wall	✏️ 上传照片并获取可供 vk_wall_post 使用的附件字符串——需要完整的用户令牌；VK 不接受社区令牌用于此操作

故事

工具	说明
vk_stories_post_photo	✏️ 发布照片故事，可使用个人身份或代表社群发布
vk_stories_post_video	✏️ 发布视频故事，可使用个人身份或代表社群发布

社群消息

需要具有 messages 权限的社群令牌，并在社群设置中启用消息功能。VK 只允许社群向先给社群发过消息或允许社群向其发送消息的人发送消息。

工具	说明
vk_messages_get_conversations	列出收件箱中的会话，按最新顺序排列；filter: "unread" 可显示等待回复的会话
vk_messages_get_history	读取一个会话
vk_messages_send	✏️ 以社群身份回复——消息会送达真实的人，因此客户端应先征求同意
vk_messages_mark_as_read	✏️ 将会话标记为已读

社群事件

VK 不允许社群令牌操作评论、点赞和墙，但会将这些内容作为事件发送给正在监听的社群。调用一次 vk_events_listen：它会启用社群的 Long Poll，并在事件类型尚未启用时将其开启（如果另一个机器人已在读取，则不会更改 API 版本），然后开始接收事件。VK 不保留历史记录：从这一刻起，服务器运行期间发生的事件才会显示。社群令牌仍无法删除评论。

工具	说明
vk_events_listen	✏️ 开始接收新评论（文本和 ID）、点赞、帖子和转发、加入和退出事件以及消息
vk_events_get	按游标读取事件；wait 最多等待 25 s 以获取下一条事件，因此 Agent 可以循环处理每条新评论

其他

工具	说明
vk_friends_get	获取用户的好友列表
vk_newsfeed_get	获取用户的新闻源
vk_likes_get	获取点赞某个对象的用户及反应数量
vk_stats_get	获取社群统计数据（仅限管理员）
vk_token_info	查看已连接的令牌、可用工具，以及要启用其他工具所需的权限

提示词

提示词会以现成工作流的形式显示在客户端中——选择一个，填写社群信息，模型就会知道要使用哪些工具。

与工具一样，提示词列表也取决于令牌：只有当令牌具备所依赖工具的权限时，才会提供相应提示词；如果令牌无法执行读取墙内容或上传图片等步骤，publish_post 就会省略这些步骤。

提示词	功能
community_digest	读取近期帖子，并总结主题、亮点和发布频率
engagement_report	按点赞数和评论数对帖子排名，然后说明表现最佳的帖子有哪些共同点
audience_snapshot	抽样查看成员，并按性别、城市和活跃度描述受众
publish_post	按社群自身的语气起草帖子，供审核后发布
find_communities	搜索相关主题的社群并比较候选结果
community_inbox	查看未读消息、总结每条消息并起草回复；仅发送你批准的内容

使用示例

配置完成后，你可以这样询问 Claude：

• “获取 Pavel Durov 的 VK 个人资料信息”
• “显示 VK 官方社群最新的 5 条帖子”
• “在我的墙上发布‘Hello World！’”
• “获取我加入的社群列表”
• “显示我的新闻源”

对话示例

以下是真实对话——这些数字是在撰写本文时从 VK 返回的。

You:    How big is the VK Mini Apps community, and how are its recent posts doing?

Claude: [vk_groups_get_by_id  group_ids="apiclub", fields="members_count,activity"]
        [vk_wall_get          domain="apiclub", count=3]

        VK Mini Apps (@vkappsdev, id 166562603) — 245,457 members, filed under
        Programming, with 898 posts on the wall. The three most recent:

        21 Jan   22,653 views   46 likes   15 reposts   "Готовы сделать этот год прорывным?..."
        20 Jul      529 views   18 likes    0 reposts   (photo post, no text)
        13 Jul    3,782 views   11 likes    3 reposts   "Суперсила игр и приложений в соцсети..."

        The January post reached forty times the audience of the July ones —
        worth a look at what it did differently.

模型收到的每个数字都是带类型的字段，而不是需要解析的文本，因为每个工具都声明了输出架构。

更新日志

请参阅 CHANGELOG.md。

测试

运行测试套件：

npm test

运行测试并生成覆盖率报告：

npm run test:coverage

API 参考

此服务封装了 VK API v5.199。详细参数文档请参阅：

• VK API 方法
• VK API 对象

安全说明

• 切勿分享你的访问令牌
• offline 范围会提供一个永不过期的令牌
• 授权前请检查权限
• 对于生产环境，请考虑使用服务令牌

贡献

欢迎贡献！请先阅读贡献指南。

1. Fork 此仓库
2. 创建你的功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 将分支推送到远程仓库（git push origin feature/amazing-feature）
5. 创建 Pull Request

许可证

MIT © 2026 bulatko

链接

• npm 软件包
• MCP 注册表
• VK API 文档
• Model Context Protocol

---

为 MCP 生态系统倾情打造 ❤️