{ "markdown": "# VK MCP Server\n\n

\n \"VK\n

\n\n

\n \"npm\n \"npm\n \"CI\"\n \"license\"\n

\n\n

\n Model Context Protocol (MCP) server for VK (VKontakte) social network API\n

\n\n

\n Enables AI assistants like Claude to interact with VK through a standardized interface.\n

\n\n\n

\n\n \"vk-mcp-server\n\n

\n\n---\n\n

\n \"A\n

\n\n

\n \"A\n

\n\n

\n Walls, communities and profiles on a host that supports MCP Apps. The\n model gets the same structured data either way — this is what the person\n sees.\n

\n\n---\n\n## Features\n\n- **19 tools** across users, walls, communities, photos, likes and statistics\n- **Read and write**: search and read freely; posting, editing and deleting are\n marked as write operations so your client can ask first\n- **Structured output**: every tool declares an output schema, so the model gets\n typed data instead of a JSON blob it has to parse out of text\n- **Pagination that explains itself**: list results say how many matches exist\n and which offset continues from here, so the model can page through a wall\n instead of stopping at the first twenty posts\n- **Things you can look at**: on hosts that support [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview)\n — Claude, Claude Desktop, VS Code Copilot, Goose — walls, communities and\n profiles render as cards: posts with their photos and clip previews,\n communities with their banner and size, profiles with avatar and following.\n Everywhere else it behaves exactly as before\n- **Prompts**: ready-made workflows — community digest, engagement report,\n audience snapshot, community search\n- **Resilient**: request timeouts, automatic backoff when VK rate-limits, and\n clear messages for captchas and HTTP failures\n- **Honest about tokens**: VK has three kinds and they differ enormously in\n reach. `--check` names which one you hold and probes what it can actually do,\n `--login` walks the VK ID flow for the reading kind, and every VK error\n carries the fix rather than the code alone\n- **Tested**: 84 tests driving the real server over the MCP protocol\n\n## Quick Start\n\n### Claude Desktop — one click\n\nDownload the latest `.mcpb` bundle from the\n[releases page](https://github.com/bulatko/vk-mcp-server/releases/latest) and\nopen it. It installs the server, asks for your VK token in a form field, and\nstores it securely — no Node.js, no config files, no terminal.\n\n### VS Code — one click\n\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_VK_MCP-0098FF?logo=visualstudiocode&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22vk%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22vk-mcp-server%22%5D%2C%22env%22%3A%7B%22VK_ACCESS_TOKEN%22%3A%22%24%7Binput%3Avk_token%7D%22%7D%2C%22inputs%22%3A%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22vk_token%22%2C%22description%22%3A%22VK%20access%20token%22%2C%22password%22%3Atrue%7D%5D%7D)\n\nVS Code prompts for your VK token and keeps it out of the config file. From a\nterminal instead:\n\n```bash\ncode --add-mcp '{\"name\":\"vk\",\"command\":\"npx\",\"args\":[\"-y\",\"vk-mcp-server\"],\"env\":{\"VK_ACCESS_TOKEN\":\"your_token\"}}'\n```\n\n### npm\n\n```bash\nnpx vk-mcp-server\n```\n\nOr install globally with `npm install -g vk-mcp-server`.\n\n### MCP Registry\n\nAlso available in the official MCP Registry:\n```\nio.github.bulatko/vk\n```\n\n## Getting VK Access Token\n\n**For anything beyond reading public pages, you need a community token.** Open\na community you manage → **Manage** → **API usage** → **Access tokens** →\n**Create token**, ticking `wall` and `photos`. Three clicks, no app, never\nexpires, tied to no browser or IP — and it is the only kind VK still lets post,\nedit or upload.\n\nFor public reads alone, either of these does:\n\n```bash\nnpx vk-mcp-server --login # sign in as yourself\n```\n\n…or the service key from any app page.\n\n**Worth knowing before you spend an evening on it:** `--login` returns a VK ID\ntoken (`vk2.a…`), which VK issues for signing in rather than for the API. It\nreads public profiles, walls and community info; posting, photos, friends,\nfeeds and statistics all answer `error 1051`, whatever scopes you request. The\nolder flow that granted full user tokens now refuses newly created apps\noutright. `npx vk-mcp-server --check` names which kind you hold and what it\nreaches.\n\nUse your own app rather than an App ID from somewhere else: a token dies with\nthe app that issued it, and the error gives no hint that this is what happened.\n\n📖 **[Full setup guide](docs/SETUP.md)** — every step with the exact screens,\nwhat the scopes unlock, remote installs, and what each error means.\n\n## Configuration\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n \"mcpServers\": {\n \"vk\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"vk-mcp-server\"],\n \"env\": {\n \"VK_ACCESS_TOKEN\": \"your_access_token_here\"\n }\n }\n }\n}\n```\n\n### Claude Code\n\nAdd to your project's `.mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"vk\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"vk-mcp-server\"],\n \"env\": {\n \"VK_ACCESS_TOKEN\": \"your_access_token_here\"\n }\n }\n }\n}\n```\n\n### Environment variables\n\n| Variable | Required | Default | Purpose |\n|----------|----------|---------|---------|\n| `VK_ACCESS_TOKEN` | for tool calls | — | VK API access token. The server starts and lists its tools without one; calling a tool then returns an error saying so |\n| `VK_TIMEOUT_MS` | no | `30000` | Abort a VK request that hangs longer than this |\n| `VK_API_BASE` | no | `https://api.vk.com/method` | Point the server at an API mirror or proxy |\n\nVK rate-limits user tokens to a few calls per second. When it answers with\nerror 6 (*too many requests*), the server backs off and retries up to three\ntimes before giving up, so short bursts of tool calls do not fail outright.\n\n## Command line\n\n| Command | What it does |\n|---------|--------------|\n| `npx vk-mcp-server` | Runs the MCP server (this is what your client calls) |\n| `npx vk-mcp-server --login ` | Gets a token through VK ID in your browser |\n| `npx vk-mcp-server --check` | Reports what your token is and which tools it can use |\n| `npx vk-mcp-server --help` | Lists the commands and environment variables |\n\n## Troubleshooting\n\nStart with:\n\n```bash\nVK_ACCESS_TOKEN=your_token npx vk-mcp-server --check\n```\n\nIt identifies which of the three token types you have — user, community or\nservice — and probes what that token can actually reach, so you find out up\nfront instead of discovering it tool by tool. It never calls a write method.\n\nCommon cases:\n\n| What you see | What it means |\n|--------------|---------------|\n| `error 8: Application is blocked` | The VK app that issued the token is blocked. Every token from it fails this way, however valid the token looks. Create your own app and issue a fresh token. |\n| `error 5: User authorization failed` | The token expired or was revoked — run `--login` again. |\n| `error 1051` or `error 28` | A service token cannot call user methods. Use a user or community token. |\n| `error 15: Access denied` | The data is restricted — a private profile, or a community that hides its members. |\n| `error 5` with `subcode 1130` | VK bound the token to the IP that authorised it, and the server is on a different one. Common when the server runs on a VPS but you signed in from your laptop. Get the token on the machine that runs the server, or use a community token. |\n| `Security Error` when authorising | The old implicit OAuth flow. Use `--login`, which does the current VK ID flow. |\n| `No VK token configured` on every tool | The server is running but your client never passed `VK_ACCESS_TOKEN` to it. Check the `env` block in your client config — a token in your shell does not reach a server the client spawns itself. |\n\nThe server turns these into messages that say what to do, so the model can\nusually explain the fix without you reading this table.\n\n## Available Tools\n\nTools marked ✏️ change something on VK — they post, edit, delete or join on\nbehalf of whoever owns the access token. Each tool also carries MCP annotations\n(`readOnlyHint`, `destructiveHint`), so a client can auto-approve lookups while\nstill asking before a post is edited or deleted.\n\n### Users\n\n| Tool | Description |\n|------|-------------|\n| `vk_users_get` | Get user profiles by IDs or screen names |\n| `vk_users_search` | Search users by name, city, age and other criteria |\n\n### Wall\n\n| Tool | Description |\n|------|-------------|\n| `vk_wall_get` | Get posts from user/community wall |\n| `vk_wall_get_by_id` | Get specific posts by `{owner_id}_{post_id}` |\n| `vk_wall_post` | ✏️ Publish a new post |\n| `vk_wall_edit` | ✏️ Edit an existing post |\n| `vk_wall_delete` | ✏️ Delete a post |\n| `vk_wall_create_comment` | ✏️ Add comment to a post |\n\n### Groups\n\n| Tool | Description |\n|------|-------------|\n| `vk_groups_get` | Get user's communities list |\n| `vk_groups_get_by_id` | Get community info by ID |\n| `vk_groups_search` | Search communities by name and criteria |\n| `vk_groups_get_members` | Get community members |\n| `vk_groups_join` | ✏️ Join a community or request to join |\n\n### Photos\n\n| Tool | Description |\n|------|-------------|\n| `vk_photos_get` | Get photos from albums |\n| `vk_photos_upload_wall` | ✏️ Upload a photo and get an attachment string for `vk_wall_post` |\n\n### Other\n\n| Tool | Description |\n|------|-------------|\n| `vk_friends_get` | Get user's friends list |\n| `vk_newsfeed_get` | Get user's newsfeed |\n| `vk_likes_get` | Get users who liked an object, with reaction counts |\n| `vk_stats_get` | Get community statistics (admin only) |\n\n## Prompts\n\nPrompts appear in your client as ready-made workflows — pick one, fill in the\ncommunity, and the model knows which tools to use.\n\n| Prompt | What it does |\n|--------|--------------|\n| `community_digest` | Reads recent posts and summarises themes, standouts and cadence |\n| `engagement_report` | Ranks posts by likes and by comments, then explains what the winners share |\n| `audience_snapshot` | Samples members and describes the audience by sex, city and activity |\n| `publish_post` | Drafts a post in the community's own tone, shows it for approval, publishes it |\n| `find_communities` | Searches communities on a topic and compares the candidates |\n\n## Usage Examples\n\nOnce configured, you can ask Claude:\n\n- \"Get information about Pavel Durov's VK profile\"\n- \"Show me the latest 5 posts from the VK official community\"\n- \"Post 'Hello World!' on my wall\"\n- \"Get the list of communities I'm a member of\"\n- \"Show my newsfeed\"\n\n### Example Conversation\n\nA real exchange — the numbers below came back from VK while this was written.\n\n```\nYou: How big is the VK Mini Apps community, and how are its recent posts doing?\n\nClaude: [vk_groups_get_by_id group_ids=\"apiclub\", fields=\"members_count,activity\"]\n [vk_wall_get domain=\"apiclub\", count=3]\n\n VK Mini Apps (@vkappsdev, id 166562603) — 245,457 members, filed under\n Programming, with 898 posts on the wall. The three most recent:\n\n 21 Jan 22,653 views 46 likes 15 reposts \"Готовы сделать этот год прорывным?...\"\n 20 Jul 529 views 18 likes 0 reposts (photo post, no text)\n 13 Jul 3,782 views 11 likes 3 reposts \"Суперсила игр и приложений в соцсети...\"\n\n The January post reached forty times the audience of the July ones —\n worth a look at what it did differently.\n```\n\nThe model gets each of those numbers as typed fields rather than text it has to\nparse, because every tool declares an output schema.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md).\n\n## Testing\n\nRun the test suite:\n\n```bash\nnpm test\n```\n\nRun tests with coverage:\n\n```bash\nnpm run test:coverage\n```\n\n## API Reference\n\nThis server wraps VK API v5.199. For detailed parameter documentation, see:\n- [VK API Methods](https://dev.vk.com/ru/method)\n- [VK API Objects](https://dev.vk.com/ru/reference)\n\n## Security Notes\n\n- Never share your access token\n- The `offline` scope provides a non-expiring token\n- Review permissions before authorizing\n- For production, consider using a service token\n\n## Contributing\n\nContributions are welcome! Please read the [Contributing Guidelines](CONTRIBUTING.md) first.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\n[MIT](LICENSE) © 2026 bulatko\n\n## Links\n\n- [npm Package](https://www.npmjs.com/package/vk-mcp-server)\n- [MCP Registry](https://registry.modelcontextprotocol.io/)\n- [VK API Documentation](https://dev.vk.com/)\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n\n---\n\n

Made with ❤️ for the MCP ecosystem

\n", "bytes": 14241, "sha": "d29e6ebea7d080e66a4bafd1ce107bca8b52e461016de2005f2cbea63c6236fc", "repo_slug": "bulatko/vk-mcp-server", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_bulatko_vk_8195cc08/readme" }