VK MCP Server

VK MCP サーバー

VKontakte（VK）向けのModel Context Protocol（MCP）サーバーです。VKはロシアおよびCIS諸国で最大のソーシャルネットワークです。

このサーバーを使用すると、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	read	基本的な読み取りメソッド	安全
social	read	ユーザー、友達＋追加機能	安全
content_read	read	約25個のコンテンツ閲覧メソッド	安全
content_publish	all	約20個のコンテンツ作成メソッド	公開できます
community_manager	all	ウォール、掲示板、グループの管理	コミュニティを変更できます
messenger	all	メッセージ＋ユーザー情報	messagesスコープが必要
analytics	read	統計、ウォール、グループの分析情報	安全
money	money	moneyモードのフィルタリングで許可される、金銭的に慎重な扱いが必要なすべてのメソッド	金銭的に慎重な扱いが必要
ads	money	広告API＋ヘルパーメソッド	金銭を使用する可能性があります
market	money	VKマーケット＋アップロードヘルパー	ショップを変更できます
commerce	money	マーケット、注文、ストア、ギフト、ドーナツ	金銭的に慎重な扱いが必要
search	read	約10個の検索メソッド	安全
full_read	read	ads／secure以外のすべての読み取りメソッド	安全
full	all	すべてのVK APIメソッド	開発専用

環境変数を使ってプロファイルを拡張できます。

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

環境変数によるプロファイルの拡張： リスト形式の変数（sections、methods、excludes）はプロファイルに追加されます。スカラー値の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. トランスポートモード

デフォルトでは、サーバーはローカル MCP クライアント向けに stdio トランスポートを使用します。リモート接続を有効にするには、HTTP に切り替えます。

VK_MCP_TRANSPORT	用途
stdio (default)	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 トランスポート認証用のベアラートークン（ループバック以外にバインドする場合は必須）

モードによるフィルタリング

サーバーは各 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 など）

AI が VK アカウントに変更を加えないようにするには、VK_MCP_MODE=read を使用します。 広告、市場、または支払い関連のツールが必要な場合は、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 はセッションベースです。生の tools/list リクエストは、initialize リクエストの後にのみ、返された Mcp-Session-Id ヘッダーを付けて送信してください。

Inspector の UI で 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以上のセクション	docs、notes、board、fave、notifications、pages、storage など	—

合計： 公式 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 エコシステム向けに開発