How do I use VK API MCP Server (FastMCP)?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@VK API MCP Server (FastMCP) send message to peer 123 saying Hi" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

VK API MCP Server (FastMCP)

🚀 Инструментальный сервер для VK API на базе FastMCP - единый интерфейс для работы с VKontakte через ИИ-агентов.

📋 Содержание

🚀 Быстрый старт

1. Клонирование и установка

cd C:\Users\nikol\Projects\mcp_vk_api
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

2. Настройка токенов

# Скопируйте и отредактируйте config.ini
copy config.ini.example config.ini

Заполните config.ini:

[vk]
token = vk1.a.your_user_token_here

[google]
speech_api_key = your_google_speech_api_key
gemini_api_key = your_gemini_api_key

3. Запуск

# Gemini CLI
mcp run C:\Users\nikol\Projects\mcp_vk_api\main.py

# Или вручную
python -u main.py

✨ Возможности

🔧 Основные функции

10 агрегаторов VK API: users, groups, messages, wall, likes, photos, docs, video, utils, recognition
Единый интерфейс: по одной функции на раздел VK API
Long Poll: ожидание событий в реальном времени
Автоматическое распознавание: речи и изображений
Имитация человеческого поведения: задержки, статусы печати
Кэширование: результатов распознавания
Пагинация и retry: надежная работа с API

🎯 Специальные возможности

await_any_event: унифицированное ожидание сообщений/уведомлений
Автоформатирование: сообщения с именами пользователей и эмодзи
Batch операции: массовые вызовы API
Capability discovery: автоматическое обнаружение методов
Универсальный клиент: vk_client.py для тестирования

📦 Установка и настройка

Требования

Python 3.11+
VK User Token с правами: messages, wall, photos, docs, video
Опционально: Google Speech API и Gemini API ключи

Зависимости

# Основные
fastmcp          # MCP сервер
vk_api           # VK API клиент
requests         # HTTP запросы

# Опционально для распознавания
google-genai     # Gemini API

Получение токенов

VK Token

Перейдите на https://vkhost.github.io/
Выберите "Kate Mobile"
Авторизуйтесь и скопируйте токен

Google API (опционально)

Speech API: https://console.cloud.google.com/apis/library/speech.googleapis.com
Gemini API: https://makersuite.google.com/app/apikey

🎮 Запуск в Gemini CLI

Глобальная установка

# Установите MCP CLI
pip install mcp

# Запустите сервер
mcp run C:\Users\nikol\Projects\mcp_vk_api\main.py

Локальный запуск

cd C:\Users\nikol\Projects\mcp_vk_api
python -u main.py

Примеры команд в Gemini CLI

# Получить информацию о пользователе
vk-api users get_user_info {"user_ids": "1", "fields": "photo_200"}

# Ожидать сообщения 5 минут
vk-api messages await_any_event {"duration_s": 300}

# Отправить сообщение
vk-api messages send_message {"peer_id": 123, "message": "Привет!"}

🖥️ Запуск в Cursor

Настройка MCP в Cursor

Откройте C:\Users\nikol\.cursor\mcp.json
Добавьте конфигурацию:

{
  "mcpServers": {
    "vk-api": {
      "command": "mcp",
      "args": ["run", "C:\\Users\\nikol\\Projects\\mcp_vk_api\\main.py"],
      "cwd": "C:\\Users\\nikol\\Projects\\mcp_vk_api"
    }
  }
}

Перезагрузите серверы: Cursor Settings → MCP → Reload Servers

Использование в Cursor

Откройте Command Palette (Ctrl+Shift+P)
Выберите "MCP: Call Tool"
Выберите vk-api и нужный агрегатор

📁 Структура проекта

mcp_vk_api/
├── 📄 main.py                    # MCP сервер, регистрация агрегаторов
├── 📄 vk_provider.py             # Инициализация VK API
├── 📄 config.py                  # Загрузка конфигурации
├── 📄 vk_client.py               # Универсальный тестовый клиент
├── 📄 requirements.txt           # Python зависимости
├── 📄 goal.txt                   # Цель проекта
├── 📄 config.ini                 # Токены и настройки
│
├── 📁 tools/                     # Агрегаторы VK API
│   ├── 📁 users/                 # Пользователи VK
│   │   └── 📄 tools.py           # get_user_info, search_users, get_friends, etc.
│   │
│   ├── 📁 groups/                # Группы VK
│   │   └── 📄 tools.py           # get_group_info, search_groups, get_members
│   │
│   ├── 📁 messages/              # Сообщения и Long Poll
│   │   ├── 📄 tools.py           # send_message, get_history, await_any_event
│   │   ├── 📄 formatting.py      # Форматирование сообщений
│   │   └── 📄 human_behavior.py  # Имитация человеческого поведения
│   │
│   ├── 📁 wall/                  # Стена и посты
│   │   └── 📄 tools.py           # get_wall_posts, create_comment, post_photo
│   │
│   ├── 📁 likes/                 # Лайки
│   │   └── 📄 tools.py           # is_liked, add, delete
│   │
│   ├── 📁 photos/                # Фотографии
│   │   └── 📄 tools.py           # photos_get, photos_get_albums
│   │
│   ├── 📁 docs/                  # Документы
│   │   └── 📄 tools.py           # docs_get, docs_search
│   │
│   ├── 📁 video/                 # Видео
│   │   └── 📄 tools.py           # video_search, video_get, video_get_direct_url
│   │
│   ├── 📁 utils/                 # Утилиты
│   │   └── 📄 tools.py           # paginate, vk_retry, resolve_screen_name
│   │
│   ├── 📁 recognition/           # Распознавание речи и изображений
│   │   ├── 📄 tools.py           # Агрегатор распознавания
│   │   ├── 📄 speech.py          # Google Speech API
│   │   ├── 📄 gemini.py          # Google Gemini API
│   │   ├── 📄 auto.py            # Автоматическое распознавание
│   │   └── 📄 cache.py           # Кэширование результатов
│   │
│   └── 📁 smart/                 # Умные функции (заготовка)
│
├── 📁 data/                      # Данные и кэш
│   ├── 📄 last_notifications.json # Время последних уведомлений
│   ├── 📄 last_ts.json           # Время последних сообщений
│   └── 📁 recognition_cache/     # Кэш распознавания
│
├── 📁 logs/                      # Логи
│   └── 📁 prompts/               # Логи промптов
│
├── 📁 tests/                     # Тесты
│   ├── 📄 mcp_likes_test.py      # Тест лайков
│   └── 📄 mcp_longpoll_test.py   # Тест Long Poll
│
└── 📁 scripts/                   # Скрипты (пусто)

🔌 API и методы

Принцип работы

Каждый агрегатор принимает два параметра:

method — строка, имя под-метода
params — объект с параметрами

Список агрегаторов

1. `users` - Пользователи VK

{
  "method": "get_user_info",
  "params": {"user_ids": "1,durov", "fields": "photo_200"}
}

Доступные методы:

get_user_info - информация о пользователях
search_users - поиск пользователей
get_friends - друзья пользователя
get_followers - подписчики
get_subscriptions - подписки
get_mutual - общие друзья
get_friend_requests - заявки в друзья
add_friend - добавить в друзья
delete_friend - удалить из друзей

2. `groups` - Группы VK

{
  "method": "get_group_info",
  "params": {"group_ids": "durov", "fields": "description"}
}

Доступные методы:

get_group_info - информация о группе
search_groups - поиск групп
get_group_members - участники группы

3. `messages` - Сообщения и Long Poll

{
  "method": "send_message",
  "params": {"peer_id": 123, "message": "Привет!", "reply_to": 456}
}

Доступные методы:

send_message - отправить сообщение
get_conversations - список диалогов
get_history - история сообщений
get_unread_messages - непрочитанные сообщения
mark_as_read - отметить как прочитанное
delete_message - удалить сообщение
edit_message - редактировать сообщение
send_photo - отправить фото
search_messages - поиск сообщений
set_typing_status - статус печати
await_any_event - ожидание событий (Long Poll)

4. `wall` - Стена и посты

{
  "method": "get_wall_posts",
  "params": {"owner_id": "-1", "count": 5}
}

Доступные методы:

get_wall_posts - получить посты
get_comments - комментарии к посту
create_comment - создать комментарий
post_photo - пост с фото
pin_post - закрепить пост
unpin_post - открепить пост
edit_post - редактировать пост
delete_post - удалить пост
watch_wall_posts - наблюдение за постами

5. `likes` - Лайки

{
  "method": "is_liked",
  "params": {"type": "post", "owner_id": "-1", "item_id": 123}
}

Доступные методы:

is_liked - проверить лайк
add - поставить лайк
delete - убрать лайк

6. `photos` - Фотографии

{
  "method": "photos_get",
  "params": {"owner_id": "1", "album_id": "profile", "count": 3}
}

Доступные методы:

photos_get - получить фотографии
photos_get_albums - альбомы фотографий
photos_get_comments - комментарии к фото
photos_create_comment - создать комментарий к фото

7. `docs` - Документы

{
  "method": "docs_search",
  "params": {"q": "инструкция", "count": 10}
}

Доступные методы:

docs_get - получить документы
docs_search - поиск документов

8. `video` - Видео

{
  "method": "video_search",
  "params": {"q": "vk", "count": 10}
}

Доступные методы:

video_search - поиск видео
video_get - получить видео
video_get_comments - комментарии к видео
video_get_direct_url - прямая ссылка на видео

9. `utils` - Утилиты

{
  "method": "list_capabilities",
  "params": {}
}

Доступные методы:

list_capabilities - список всех методов
describe - описание метода
paginate - пагинация
vk_retry - надежный вызов API
resolve_screen_name - разрешение короткого имени
resolve_cached - кэшируемое разрешение
execute_batch - пакетный вызов

10. `recognition` - Распознавание

{
  "method": "transcribe_speech",
  "params": {"audio_source": "https://example.com/audio.mp3", "language": "ru-RU"}
}

Доступные методы:

transcribe_speech - распознавание речи
analyze_image - анализ изображения
get_supported_languages - поддерживаемые языки
get_available_features - доступные функции

💡 Примеры использования

Базовые операции

Получение информации о пользователе

{
  "method": "get_user_info",
  "params": {
    "user_ids": "1,durov",
    "fields": "photo_200,city,verified"
  }
}

Поиск пользователей

{
  "method": "search_users",
  "params": {
    "q": "Павел Дуров",
    "count": 5
  }
}

Отправка сообщения

{
  "method": "send_message",
  "params": {
    "peer_id": 123456789,
    "message": "Привет! Как дела?",
    "reply_to": 987654321
  }
}

Ожидание событий (Long Poll)

{
  "method": "await_any_event",
  "params": {
    "duration_s": 300
  }
}

Продвинутые операции

Пагинация диалогов

{
  "method": "paginate",
  "params": {
    "api_method": "messages.getConversations",
    "params": {},
    "max_items": 50,
    "page_size": 20
  }
}

Пакетный вызов API

{
  "method": "execute_batch",
  "params": {
    "calls": [
      {"method": "users.get", "params": {"user_ids": "1"}},
      {"method": "users.get", "params": {"user_ids": "2"}}
    ]
  }
}

Распознавание речи

{
  "method": "transcribe_speech",
  "params": {
    "audio_source": "C:/path/to/voice_message.mp3",
    "language": "ru-RU",
    "source_type": "file"
  }
}

Анализ изображения

{
  "method": "analyze_image",
  "params": {
    "image_source": "https://example.com/image.jpg",
    "source_type": "url"
  }
}

🧪 Отладка и тестирование

Универсальный клиент

# Тестирование через vk_client.py
python vk_client.py messages --args '{"method":"await_any_event","params":{"duration_s":60}}'

# Красивый вывод
python vk_client.py users --args '{"method":"get_user_info","params":{"user_ids":"1"}}' --pretty

# Из файла
python vk_client.py messages --args-file test_args.json

Прямой вызов (без MCP)

# Для отладки
python vk_client.py messages --direct --args '{"method":"get_conversations","params":{"count":5}}'

Логирование

# Запуск с подробными логами
python -u main.py 2>&1 | tee vk_api.log

Проверка токенов

# Тест VK API
python vk_client.py users --args '{"method":"get_user_info","params":{"user_ids":"1"}}'

# Тест Google API (если настроены)
python vk_client.py recognition --args '{"method":"get_supported_languages","params":{}}'

🔧 Troubleshooting

Частые проблемы

1. "VK API not initialized"

Причина: Неверный токен или отсутствует config.ini Решение:

# Проверьте config.ini
cat config.ini

# Получите новый токен на https://vkhost.github.io/

2. "Skipping tool ... missing types"

Причина: Проблема с MCP сервером Решение:

# Перезагрузите MCP servers в Cursor
# Или перезапустите сервер
python -u main.py

3. "No prompts or tools found"

Причина: Неправильная конфигурация MCP Решение:

// Проверьте C:\Users\nikol\.cursor\mcp.json
{
  "mcpServers": {
    "vk-api": {
      "command": "mcp",
      "args": ["run", "C:\\Users\\nikol\\Projects\\mcp_vk_api\\main.py"],
      "cwd": "C:\\Users\\nikol\\Projects\\mcp_vk_api"
    }
  }
}

4. Ошибки распознавания

Причина: Отсутствуют Google API ключи Решение:

# Установите google-genai
pip install google-genai

# Добавьте ключи в config.ini
[google]
speech_api_key = your_speech_api_key
gemini_api_key = your_gemini_api_key

5. "await_any_event" ждет только 60 секунд

Причина: Проблема с таймаутом Решение: Обновлено в коде - теперь корректно работает с указанным duration_s

Отладка Long Poll

# Тест ожидания событий
python vk_client.py messages --args '{"method":"await_any_event","params":{"duration_s":120}}'

# Проверка непрочитанных сообщений
python vk_client.py messages --args '{"method":"get_unread_messages","params":{}}'

Проверка прав токена

# Тест основных функций
python vk_client.py users --args '{"method":"get_user_info","params":{"user_ids":"1"}}'
python vk_client.py messages --args '{"method":"get_conversations","params":{"count":1}}'
python vk_client.py wall --args '{"method":"get_wall_posts","params":{"owner_id":"1","count":1}}'

🔒 Безопасность

Переменные окружения

# Альтернатива config.ini
export VK_TOKEN="vk1.a.your_token"
export GOOGLE_SPEECH_API_KEY="your_speech_key"
export GOOGLE_GEMINI_API_KEY="your_gemini_key"

🚀 Особенности и возможности

Автоматическое распознавание

Голосовые сообщения распознаются автоматически при получении истории
Кэширование результатов для экономии API вызовов
Поддержка множества языков через Google Speech API

Имитация человеческого поведения

Автоматические задержки при печати сообщений
Статусы "печатает" для реалистичности
Настраиваемые интервалы между действиями

Красивое форматирование

Имена пользователей вместо ID
Эмодзи и иконки для разных типов контента
Структурированный вывод для удобства чтения

Универсальные утилиты

Пагинация для больших списков
Retry механизм для надежности
Batch операции для эффективности
Кэширование для оптимизации

📞 Поддержка

Полезные команды

# Список всех методов
python vk_client.py utils --args '{"method":"list_capabilities","params":{}}'

# Описание конкретного метода
python vk_client.py utils --args '{"method":"describe","params":{"aggregator":"messages","method":"await_any_event"}}'

# Статистика распознавания
python vk_client.py messages --args '{"method":"get_recognition_statistics","params":{}}'

# Очистка кэша
python vk_client.py messages --args '{"method":"clear_recognition_cache_data","params":{}}'

Логи и отладка

Логи сервера: python -u main.py 2>&1 | tee vk_api.log
Тестовые файлы: tests/mcp_*.py
Кэш данных: data/recognition_cache/

🎯 Цель проекта: Быть проактивным и полезным ассистентом в VK. Проверять новые сообщения и отвечать на них осмысленно.

📝 Лицензия: Проект для личного использования и обучения.

VK API MCP Server (FastMCP)

📋 Содержание

🚀 Быстрый старт

1. Клонирование и установка

2. Настройка токенов

3. Запуск

✨ Возможности

🔧 Основные функции

🎯 Специальные возможности

📦 Установка и настройка

Требования

Зависимости

Получение токенов

VK Token

Google API (опционально)

🎮 Запуск в Gemini CLI

Глобальная установка

Локальный запуск

Примеры команд в Gemini CLI

🖥️ Запуск в Cursor

Настройка MCP в Cursor

Использование в Cursor

📁 Структура проекта

🔌 API и методы

Принцип работы

Список агрегаторов

1. users - Пользователи VK

2. groups - Группы VK

3. messages - Сообщения и Long Poll

4. wall - Стена и посты

5. likes - Лайки

6. photos - Фотографии

7. docs - Документы

8. video - Видео

9. utils - Утилиты

10. recognition - Распознавание

💡 Примеры использования

Базовые операции

Получение информации о пользователе

Поиск пользователей

Отправка сообщения

Ожидание событий (Long Poll)

Продвинутые операции

Пагинация диалогов

Пакетный вызов API

Распознавание речи

Анализ изображения

🧪 Отладка и тестирование

Универсальный клиент

Прямой вызов (без MCP)

Логирование

Проверка токенов

🔧 Troubleshooting

Частые проблемы

1. "VK API not initialized"

2. "Skipping tool ... missing types"

3. "No prompts or tools found"

4. Ошибки распознавания

5. "await_any_event" ждет только 60 секунд

Отладка Long Poll

Проверка прав токена

🔒 Безопасность

Рекомендации

Переменные окружения

🚀 Особенности и возможности

Автоматическое распознавание

Имитация человеческого поведения

Красивое форматирование

Универсальные утилиты

📞 Поддержка

Полезные команды

Логи и отладка

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

1. `users` - Пользователи VK

2. `groups` - Группы VK

3. `messages` - Сообщения и Long Poll

4. `wall` - Стена и посты

5. `likes` - Лайки

6. `photos` - Фотографии

7. `docs` - Документы

8. `video` - Видео

9. `utils` - Утилиты

10. `recognition` - Распознавание