VK API MCP Server (FastMCP)

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

📋 Содержание

• Быстрый старт
• Возможности
• Установка и настройка
• Запуск в Gemini CLI
• Запуск в Cursor
• Структура проекта
• API и методы
• Примеры использования
• Отладка и тестирование
• Troubleshooting

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

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

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

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

1. Speech API: https://console.cloud.google.com/apis/library/speech.googleapis.com
2. 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

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

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

3. Перезагрузите серверы: 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 с токенами
• ✅ Храните токены только локально
• ✅ Используйте переменные окружения для API ключей
• ✅ Регулярно обновляйте токены VK
• ❌ Не передавайте токены третьим лицам

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

# Альтернатива 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. Проверять новые сообщения и отвечать на них осмысленно.

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