# VK MCP Server

<p align="center">
  <img src="https://upload.wikimedia.org/wikipedia/commons/2/21/VK.com-logo.svg" width="100" alt="VK Logo">
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/vk-mcp-server"><img src="https://img.shields.io/npm/v/vk-mcp-server.svg" alt="npm version"></a>
  <a href="https://www.npmjs.com/package/vk-mcp-server"><img src="https://img.shields.io/npm/dm/vk-mcp-server.svg" alt="npm downloads"></a>
  <a href="https://github.com/bulatko/vk-mcp-server/actions"><img src="https://github.com/bulatko/vk-mcp-server/workflows/CI/badge.svg" alt="CI"></a>
  <a href="https://github.com/bulatko/vk-mcp-server/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/vk-mcp-server.svg" alt="license"></a>
</p>

<p align="center">
  <strong>Model Context Protocol (MCP) server for VK (VKontakte) social network API</strong>
</p>

<p align="center">
  Enables AI assistants like Claude to interact with VK through a standardized interface.
</p>


<p align="center">
<a href="https://glama.ai/mcp/servers/bulatko/vk-mcp-server">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/bulatko/vk-mcp-server/badge" alt="vk-mcp-server MCP server" />
</a>
</p>

---

<p align="center">
  <img src="docs/img/wall-card.jpg" width="420" alt="A VK wall rendered as a card in the chat: posts with their photos, clip previews and counters" />
</p>

<p align="center">
  <img src="docs/img/entity-cards.jpg" width="720" alt="A community and a profile rendered as cards: banner, avatar, size and description on one; avatar, location and following on the other" />
</p>

<p align="center">
  <em>Walls, communities and profiles on a host that supports MCP Apps. The
  model gets the same structured data either way — this is what the person
  sees.</em>
</p>

---

## Features

- **19 tools** across users, walls, communities, photos, likes and statistics
- **Read and write**: search and read freely; posting, editing and deleting are
  marked as write operations so your client can ask first
- **Structured output**: every tool declares an output schema, so the model gets
  typed data instead of a JSON blob it has to parse out of text
- **Pagination that explains itself**: list results say how many matches exist
  and which offset continues from here, so the model can page through a wall
  instead of stopping at the first twenty posts
- **Things you can look at**: on hosts that support [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview)
  — Claude, Claude Desktop, VS Code Copilot, Goose — walls, communities and
  profiles render as cards: posts with their photos and clip previews,
  communities with their banner and size, profiles with avatar and following.
  Everywhere else it behaves exactly as before
- **Prompts**: ready-made workflows — community digest, engagement report,
  audience snapshot, community search
- **Resilient**: request timeouts, automatic backoff when VK rate-limits, and
  clear messages for captchas and HTTP failures
- **Honest about tokens**: VK has three kinds and they differ enormously in
  reach. `--check` names which one you hold and probes what it can actually do,
  `--login` walks the VK ID flow for the reading kind, and every VK error
  carries the fix rather than the code alone
- **Tested**: 84 tests driving the real server over the MCP protocol

## Quick Start

### Claude Desktop — one click

Download the latest `.mcpb` bundle from the
[releases page](https://github.com/bulatko/vk-mcp-server/releases/latest) and
open it. It installs the server, asks for your VK token in a form field, and
stores it securely — no Node.js, no config files, no terminal.

### VS Code — one click

[![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)

VS Code prompts for your VK token and keeps it out of the config file. From a
terminal instead:

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

### npm

```bash
npx vk-mcp-server
```

Or install globally with `npm install -g vk-mcp-server`.

### MCP Registry

Also available in the official MCP Registry:
```
io.github.bulatko/vk
```

## Getting VK Access Token

**For anything beyond reading public pages, you need a community token.** Open
a community you manage → **Manage** → **API usage** → **Access tokens** →
**Create token**, ticking `wall` and `photos`. Three clicks, no app, never
expires, tied to no browser or IP — and it is the only kind VK still lets post,
edit or upload.

For public reads alone, either of these does:

```bash
npx vk-mcp-server --login <YOUR_APP_ID>   # sign in as yourself
```

…or the service key from any app page.

**Worth knowing before you spend an evening on it:** `--login` returns a VK ID
token (`vk2.a…`), which VK issues for signing in rather than for the API. It
reads public profiles, walls and community info; posting, photos, friends,
feeds and statistics all answer `error 1051`, whatever scopes you request. The
older flow that granted full user tokens now refuses newly created apps
outright. `npx vk-mcp-server --check` names which kind you hold and what it
reaches.

Use your own app rather than an App ID from somewhere else: a token dies with
the app that issued it, and the error gives no hint that this is what happened.

📖 **[Full setup guide](docs/SETUP.md)** — every step with the exact screens,
what the scopes unlock, remote installs, and what each error means.

## Configuration

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

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

### Claude Code

Add to your project's `.mcp.json`:

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

### Environment variables

| Variable | Required | Default | Purpose |
|----------|----------|---------|---------|
| `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 |
| `VK_TIMEOUT_MS` | no | `30000` | Abort a VK request that hangs longer than this |
| `VK_API_BASE` | no | `https://api.vk.com/method` | Point the server at an API mirror or proxy |

VK rate-limits user tokens to a few calls per second. When it answers with
error 6 (*too many requests*), the server backs off and retries up to three
times before giving up, so short bursts of tool calls do not fail outright.

## Command line

| Command | What it does |
|---------|--------------|
| `npx vk-mcp-server` | Runs the MCP server (this is what your client calls) |
| `npx vk-mcp-server --login <APP_ID>` | Gets a token through VK ID in your browser |
| `npx vk-mcp-server --check` | Reports what your token is and which tools it can use |
| `npx vk-mcp-server --help` | Lists the commands and environment variables |

## Troubleshooting

Start with:

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

It identifies which of the three token types you have — user, community or
service — and probes what that token can actually reach, so you find out up
front instead of discovering it tool by tool. It never calls a write method.

Common cases:

| What you see | What it means |
|--------------|---------------|
| `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. |
| `error 5: User authorization failed` | The token expired or was revoked — run `--login` again. |
| `error 1051` or `error 28` | A service token cannot call user methods. Use a user or community token. |
| `error 15: Access denied` | The data is restricted — a private profile, or a community that hides its members. |
| `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. |
| `Security Error` when authorising | The old implicit OAuth flow. Use `--login`, which does the current VK ID flow. |
| `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. |

The server turns these into messages that say what to do, so the model can
usually explain the fix without you reading this table.

## Available Tools

Tools marked ✏️ change something on VK — they post, edit, delete or join on
behalf of whoever owns the access token. Each tool also carries MCP annotations
(`readOnlyHint`, `destructiveHint`), so a client can auto-approve lookups while
still asking before a post is edited or deleted.

### Users

| Tool | Description |
|------|-------------|
| `vk_users_get` | Get user profiles by IDs or screen names |
| `vk_users_search` | Search users by name, city, age and other criteria |

### Wall

| Tool | Description |
|------|-------------|
| `vk_wall_get` | Get posts from user/community wall |
| `vk_wall_get_by_id` | Get specific posts by `{owner_id}_{post_id}` |
| `vk_wall_post` | ✏️ Publish a new post |
| `vk_wall_edit` | ✏️ Edit an existing post |
| `vk_wall_delete` | ✏️ Delete a post |
| `vk_wall_create_comment` | ✏️ Add comment to a post |

### Groups

| Tool | Description |
|------|-------------|
| `vk_groups_get` | Get user's communities list |
| `vk_groups_get_by_id` | Get community info by ID |
| `vk_groups_search` | Search communities by name and criteria |
| `vk_groups_get_members` | Get community members |
| `vk_groups_join` | ✏️ Join a community or request to join |

### Photos

| Tool | Description |
|------|-------------|
| `vk_photos_get` | Get photos from albums |
| `vk_photos_upload_wall` | ✏️ Upload a photo and get an attachment string for `vk_wall_post` |

### Other

| Tool | Description |
|------|-------------|
| `vk_friends_get` | Get user's friends list |
| `vk_newsfeed_get` | Get user's newsfeed |
| `vk_likes_get` | Get users who liked an object, with reaction counts |
| `vk_stats_get` | Get community statistics (admin only) |

## Prompts

Prompts appear in your client as ready-made workflows — pick one, fill in the
community, and the model knows which tools to use.

| Prompt | What it does |
|--------|--------------|
| `community_digest` | Reads recent posts and summarises themes, standouts and cadence |
| `engagement_report` | Ranks posts by likes and by comments, then explains what the winners share |
| `audience_snapshot` | Samples members and describes the audience by sex, city and activity |
| `publish_post` | Drafts a post in the community's own tone, shows it for approval, publishes it |
| `find_communities` | Searches communities on a topic and compares the candidates |

## Usage Examples

Once configured, you can ask Claude:

- "Get information about Pavel Durov's VK profile"
- "Show me the latest 5 posts from the VK official community"
- "Post 'Hello World!' on my wall"
- "Get the list of communities I'm a member of"
- "Show my newsfeed"

### Example Conversation

A real exchange — the numbers below came back from VK while this was written.

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

The model gets each of those numbers as typed fields rather than text it has to
parse, because every tool declares an output schema.

## Changelog

See [CHANGELOG.md](CHANGELOG.md).

## Testing

Run the test suite:

```bash
npm test
```

Run tests with coverage:

```bash
npm run test:coverage
```

## API Reference

This server wraps VK API v5.199. For detailed parameter documentation, see:
- [VK API Methods](https://dev.vk.com/ru/method)
- [VK API Objects](https://dev.vk.com/ru/reference)

## Security Notes

- Never share your access token
- The `offline` scope provides a non-expiring token
- Review permissions before authorizing
- For production, consider using a service token

## Contributing

Contributions are welcome! Please read the [Contributing Guidelines](CONTRIBUTING.md) first.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

[MIT](LICENSE) © 2026 bulatko

## Links

- [npm Package](https://www.npmjs.com/package/vk-mcp-server)
- [MCP Registry](https://registry.modelcontextprotocol.io/)
- [VK API Documentation](https://dev.vk.com/)
- [Model Context Protocol](https://modelcontextprotocol.io/)

---

<p align="center">Made with ❤️ for the MCP ecosystem</p>