{
  "markdown": "# VK MCP Server\n\nModel Context Protocol (MCP) server for [VKontakte](https://vk.com) (VK) — the largest social network in Russia and CIS countries.\n\nThis server allows AI assistants (Claude, Cursor, Windsurf, VS Code, etc.) to interact with VK through a standardized MCP interface.\n\n## Features\n\n- **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\n- **Auto-generated from VK API schema** — always up-to-date with the official API\n- **Read/Write/Money mode filtering** — restrict AI to read-only, allow non-financial writes, or enable financially sensitive methods\n- **Section filtering** — include or exclude specific API sections (e.g., disable `ads`, `secure`)\n- **`.env` support** — load token from environment file for local development\n- **VK upload API helpers** — exposes upload-server and save methods for media workflows\n- **ESM-based** — modern Node.js module system\n- **Multiple transports** — stdio (for Claude Desktop / Cursor), Streamable HTTP and SSE (for remote MCP clients like Grok)\n\n## Prerequisites\n\n- Node.js ≥ 18\n- VK Access Token with required permissions\n\n## Installation\n\n### Option 1: Run with npx (no install)\n\n```bash\nnpx full-vk-mcp\n```\n\n### Option 2: Install globally\n\n```bash\nnpm install -g full-vk-mcp\nfull-vk-mcp\n```\n\n### Option 3: Clone from GitHub\n\n```bash\ngit clone https://github.com/ssm82/full-vk-mcp.git\ncd full-vk-mcp\nnpm install\nnode src/index.js\n```\n\nThe VK API schema is downloaded **automatically** on the first run. No manual steps needed.\n\n## Configuration\n\n### 1. VK Access Token\n\nCreate a `.env` file in the project root:\n\n```bash\nVK_ACCESS_TOKEN=your_vk_token_here\n```\n\nOr get a token from:\n- [vkhost.github.io](https://vkhost.github.io/) — quick token generator\n- [VK Dev](https://dev.vk.com/) — official developer portal\n\n**Required permissions depend on your use case:**\n- `wall` — posting and reading wall\n- `photos` — uploading photos\n- `groups` — community management\n- `friends`, `messages`, `market`, `stats` — as needed\n\n> **Security:** Never commit your token to git. The `.env` file is already in `.gitignore`.\n\n### 2. Choose a Profile (Recommended)\n\nInstead of manually configuring sections and methods, use a built-in profile via `VK_MCP_PROFILE`:\n\n```bash\nVK_MCP_PROFILE=minimal npx full-vk-mcp\n```\n\n| Profile | Mode | Description | Warning |\n|---------|------|-------------|---------|\n| `minimal` | read | Essential read methods | Safe |\n| `social` | read | Users, friends + extras | Safe |\n| `content_read` | read | ~25 content viewing methods | Safe |\n| `content_publish` | all | ~20 content creation methods | Can publish |\n| `community_manager` | all | Wall, board, groups management | Can modify communities |\n| `messenger` | all | Messages + user info | Requires `messages` scope |\n| `analytics` | read | Stats, wall, groups insights | Safe |\n| `money` | money | All financially sensitive methods allowed by money-mode filtering | **Financially sensitive** |\n| `ads` | money | Ads API + helper methods | **Can spend money** |\n| `market` | money | VK Market + upload helpers | Can modify shop |\n| `commerce` | money | Market, orders, store, gifts, donut | Financially sensitive |\n| `search` | read | ~10 search methods | Safe |\n| `full_read` | read | All read methods except ads/secure | Safe |\n| `full` | all | **All VK API methods** | **Development only** |\n\nProfiles can be extended with environment variables:\n\n```bash\nVK_MCP_PROFILE=social VK_MCP_INCLUDE_SECTIONS=wall npx full-vk-mcp\n```\n\n> **Env extends profile:** list variables (sections, methods, excludes) are merged with the profile; scalar `mode` is overridden by env.\n\n### 3. MCP Client Setup\n\n#### VS Code (with Copilot / Claude / etc.)\n\nCreate `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"vk\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"full-vk-mcp\"],\n      \"env\": {\n        \"VK_ACCESS_TOKEN\": \"${input:vk-token}\",\n        \"VK_MCP_PROFILE\": \"minimal\"\n      }\n    }\n  },\n  \"inputs\": [\n    {\n      \"type\": \"promptString\",\n      \"id\": \"vk-token\",\n      \"description\": \"VK Access Token\",\n      \"password\": true\n    }\n  ]\n}\n```\n\nFor local development from a cloned repository, use:\n\n```json\n{\n  \"command\": \"node\",\n  \"args\": [\"/absolute/path/to/full-vk-mcp/src/index.js\"]\n}\n```\n\n#### Cursor\n\nCreate `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"vk\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"full-vk-mcp\"],\n      \"env\": {\n        \"VK_ACCESS_TOKEN\": \"your_token\",\n        \"VK_MCP_PROFILE\": \"social\"\n      }\n    }\n  }\n}\n```\n\n#### Claude Desktop\n\nEdit `claude_desktop_config.json`:\n\n- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows:** `%APPDATA%/Claude/claude_desktop_config.json`\n- **Linux:** `~/.config/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"vk\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"full-vk-mcp\"],\n      \"env\": {\n        \"VK_ACCESS_TOKEN\": \"your_token\",\n        \"VK_MCP_PROFILE\": \"minimal\"\n      }\n    }\n  }\n}\n```\n\nFor local development from a cloned repository, use:\n\n```json\n{\n  \"command\": \"node\",\n  \"args\": [\"/absolute/path/to/full-vk-mcp/src/index.js\"]\n}\n```\n\n#### Windsurf / Other MCP Clients\n\nUse the stdio transport and provide `VK_ACCESS_TOKEN` via environment variables.\n\n### 4. Transport Mode\n\nBy default, the server uses **stdio** transport for local MCP clients. To enable remote connections, switch to HTTP:\n\n| `VK_MCP_TRANSPORT` | Use case |\n|--------------------|----------|\n| `stdio` (default)  | Claude Desktop, Cursor, VS Code, Windsurf |\n| `http`             | Grok, ChatGPT, remote MCP clients |\n| `sse`              | Same as `http` (both endpoints enabled) |\n\n```bash\n# HTTP mode for remote clients\nVK_ACCESS_TOKEN=your_token VK_MCP_TRANSPORT=http npx full-vk-mcp\n```\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `VK_ACCESS_TOKEN` | *(required)* | Your VK API access token |\n| `VK_MCP_PROFILE` | — | Built-in profile name (`minimal`, `social`, `full`, etc.) |\n| `VK_MCP_MODE` | `read` | `read` — read-only, `write` — non-financial writes, `money` — financially sensitive, `all` — everything |\n| `VK_MCP_INCLUDE_SECTIONS` | — | Comma-separated whitelist of API sections. Without a profile, safe subset (`users`, `groups`, `wall`, `friends`, `photos`) is used |\n| `VK_MCP_EXCLUDE_SECTIONS` | `ads,secure,market,orders,store,gifts,donut,votes` *(without profile / without explicit includes)* | Comma-separated blacklist of API sections. Skipped when `VK_MCP_INCLUDE_SECTIONS` or `VK_MCP_INCLUDE_METHODS` is set |\n| `VK_MCP_INCLUDE_METHODS` | — | Comma-separated whitelist of methods (e.g., `users.get,wall.get`) |\n| `VK_MCP_EXCLUDE_METHODS` | — | Comma-separated blacklist of methods |\n| `VK_MCP_MAX_TOOLS` | — | Limit the number of exposed tools |\n| `VK_MCP_TRANSPORT` | `stdio` | Transport type: `stdio`, `http`, or `sse` |\n| `VK_MCP_PORT` | `3000` | HTTP port (falls back to `$PORT` for PaaS like Render) |\n| `VK_MCP_HOST` | `127.0.0.1` | Bind address. Use `0.0.0.0` for public hosts |\n| `VK_MCP_AUTH_TOKEN` | — | Bearer token for HTTP transport auth (required when binding to non-loopback) |\n\n### Mode Filtering\n\nThe server automatically classifies each VK API method into risk levels:\n\n| Mode | Description | Sections |\n|------|-------------|----------|\n| `read` | Read-only methods | Safe subset: `users`, `groups`, `wall`, `friends`, `photos` |\n| `write` | Read + non-financial writes | Can modify your account (post, edit, delete, send, etc.) |\n| `money` | Financially sensitive only | `ads`, `market`, `orders`, `store`, `gifts`, `donut`, `votes`, selected `secure.*` |\n| `all` | Everything | Read + write + money — no restrictions |\n\n- **Read** methods — `get*`, `search*`, `is*`, `are*`, `check*`, `resolve*`, `find*`, `count*`, `lookup*`, `list*`\n- **Write** methods — everything else (post, edit, delete, send, etc.)\n- **Money** methods — any method in financial sections or explicitly tagged (`secure.getAppBalance`, etc.)\n\nUse `VK_MCP_MODE=read` to prevent the AI from making any changes to your VK account.\nUse `VK_MCP_MODE=money` when you need ads, market, or payment-related tools.\n\n## Running Locally\n\nWith npm/npx:\n\n```bash\nVK_ACCESS_TOKEN=your_token npx full-vk-mcp\n```\n\nWith a cloned repository:\n\n```bash\n# With .env file (recommended for development)\nnode src/index.js\n\n# Or inline\nVK_ACCESS_TOKEN=your_token node src/index.js\n\n# Use a profile\nVK_ACCESS_TOKEN=your_token VK_MCP_PROFILE=minimal node src/index.js\n\n# Read-only mode\nVK_ACCESS_TOKEN=your_token VK_MCP_MODE=read node src/index.js\n\n# Include only specific sections\nVK_ACCESS_TOKEN=your_token VK_MCP_INCLUDE_SECTIONS=users,wall node src/index.js\n```\n\n### HTTP Mode\n\n```bash\n# Start HTTP server (localhost only, no auth)\nVK_ACCESS_TOKEN=your_token VK_MCP_TRANSPORT=http npx full-vk-mcp\n\n# With custom port\nVK_MCP_TRANSPORT=http VK_MCP_PORT=8080 npx full-vk-mcp\n\n# Public deploy (auth required)\nVK_MCP_TRANSPORT=http VK_MCP_HOST=0.0.0.0 VK_MCP_AUTH_TOKEN=your_secret npx full-vk-mcp\n```\n\n### Test HTTP endpoint\n\n```bash\n# Health check\ncurl http://127.0.0.1:3000/health\n```\n\nFor full MCP protocol testing, use the MCP Inspector:\n\n```bash\nnpx @modelcontextprotocol/inspector\n```\n\nThen select:\n\n```text\nTransport: Streamable HTTP\nURL: http://127.0.0.1:3000/mcp\n```\n\nStreamable 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.\n\nIn the Inspector UI select **Streamable HTTP** and enter `http://127.0.0.1:3000/mcp`.\n\n## Available Tools (by Category)\n\n| Category | Examples | Count |\n|----------|----------|-------|\n| **Wall** | `vk_wall_get`, `vk_wall_post`, `vk_wall_edit`, `vk_wall_delete`, `vk_wall_search` | 10+ |\n| **Users** | `vk_users_get`, `vk_users_search`, `vk_users_get_followers` | 5+ |\n| **Groups** | `vk_groups_get`, `vk_groups_get_members`, `vk_groups_search`, `vk_groups_join` | 20+ |\n| **Photos** | `vk_photos_get`, `vk_photos_get_upload_server`, `vk_photos_save` | 15+ |\n| **Videos** | `vk_video_get`, `vk_video_search`, `vk_video_save` | 10+ |\n| **Messages** | `vk_messages_get_history`, `vk_messages_get_conversations`, `vk_messages_send` | 20+ |\n| **Friends** | `vk_friends_get`, `vk_friends_get_online`, `vk_friends_add` | 10+ |\n| **Market** | `vk_market_get`, `vk_market_search`, `vk_market_get_orders` | 10+ |\n| **Stories** | `vk_stories_get`, `vk_stories_get_upload_server` | 5+ |\n| **Polls** | `vk_polls_create`, `vk_polls_get_by_id`, `vk_polls_add_vote` | 5+ |\n| **Stats** | `vk_stats_get`, `vk_stats_get_post_reach` | 2+ |\n| **Ads** | `vk_ads_get_campaigns`, `vk_ads_get_ads`, `vk_ads_get_statistics` | 15+ |\n| **+ 60 more sections** | docs, notes, board, fave, notifications, pages, storage, etc. | — |\n\n> **Total:** 180+ tools auto-generated from the official VK API schema.\n\n## Examples\n\n### Get your wall posts\n\n```\nTool: vk_wall_get\nArguments: { \"count\": 5 }\n```\n\n### Search for users\n\n```\nTool: vk_users_search\nArguments: { \"q\": \"Ivan Ivanov\", \"count\": 10 }\n```\n\n### Get community members\n\n```\nTool: vk_groups_get_members\nArguments: { \"group_id\": \"apiclub\", \"count\": 100 }\n```\n\n### Create a poll\n\n```\nTool: vk_polls_create\nArguments: {\n  \"question\": \"What's your favorite color?\",\n  \"add_answers\": \"[\\\"Red\\\", \\\"Green\\\", \\\"Blue\\\"]\"\n}\n```\n\n## Deployment\n\nFor Render, Railway, Fly.io, or similar PaaS:\n\n```bash\n# build command\nnpm install\n\n# start command (when deploying from repository)\nnode src/index.js\n\n# or when deploying from npm package\nnpx full-vk-mcp\n\n# environment variables\nVK_ACCESS_TOKEN=...\nVK_MCP_TRANSPORT=http\nVK_MCP_HOST=0.0.0.0\nVK_MCP_PORT=3000        # or omit to use $PORT (Render auto-sets it)\nVK_MCP_AUTH_TOKEN=...   # required for public access\nVK_MCP_MODE=read        # or your chosen profile/mode\n```\n\n> **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.\n\n## Development\n\n```bash\n# Run tests (schema downloads automatically on first run)\nnpm test\n\n# Start the server\nnode src/index.js\n```\n\n## Project Structure\n\n```\nfull-vk-mcp/\n├── src/\n│   ├── index.js           # Entry point (transport switching)\n│   ├── server-factory.js  # MCP server factory\n│   ├── http-transport.js  # HTTP/SSE transport\n│   ├── schema-loader.js   # Loads and filters VK API schema\n│   ├── tool-registry.js   # Builds MCP tools from schema\n│   ├── param-converter.js # Converts VK params to JSON Schema\n│   ├── profiles.js        # Built-in profiles\n│   └── vk-client.js       # VK API HTTP client\n├── vk-api-schema/         # Official VK API schema (JSON) — see note below\n├── tests.test.js          # Test suite\n├── .env                   # Your token (gitignored)\n├── package.json\n└── README.md\n```\n\n> **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.\n\n## VK API Schema\n\nThe 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:\n\n```\nhttps://github.com/VKCOM/vk-api-schema\n```\n\nThe schema is saved to `vk-api-schema/` in the project root and cached for subsequent runs.\n\n### Updating the Schema\n\nTo get the latest VK API changes, delete the cached folder and restart:\n\n```bash\nrm -rf vk-api-schema/\nnode src/index.js  # schema will be re-downloaded automatically\n```\n\n## Security\n\n- **Token storage:** Use `.env` or your MCP client's secure environment variables. Never commit tokens.\n- **Least privilege:** Use `VK_MCP_MODE=read` if the AI only needs to read data.\n- **Section filtering:** Exclude sensitive sections like `ads`, `secure` if not needed.\n- **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.\n\n## Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| `VK_ACCESS_TOKEN is required` | Create `.env` file or set the environment variable |\n| `Unknown tool` | Check that the method name uses snake_case (`vk_wall_get` not `vk.wall.get`) |\n| `Access denied` | Your token lacks the required VK permission scope |\n| Too many tools | Use `VK_MCP_INCLUDE_SECTIONS` or `VK_MCP_MODE=read` to filter |\n| HTTP `Not Acceptable` | Add header `Accept: application/json, text/event-stream` |\n| HTTP `VK_MCP_AUTH_TOKEN is required` | Set auth token when binding to `0.0.0.0` |\n\n## License\n\nMIT\n\n## Contributing\n\nPull requests are welcome! Please open an issue first to discuss major changes.\n\n---\n\n**Made for the [Model Context Protocol](https://modelcontextprotocol.io/) ecosystem**\n",
  "bytes": 14945,
  "sha": "f35142c168219ee1461ff249ff84ad5bb0b6dfd3085b72b6706642a6104ca432",
  "repo_slug": "ssm82/full-vk-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ssm82_vk_mcp_d4134fa4/readme"
}