vk_mcp_server

Nikolay1221/vk_mcp_server

3.3

If you are the rightful owner of vk_mcp_server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

VK API MCP Server (FastMCP) is a tool-based server for interacting with VKontakte through AI agents, providing a unified interface for VK API operations.

Tools
10
Resources
0
Prompts
0

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
  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"
    }
  }
}
  1. Перезагрузите серверы: 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. Проверять новые сообщения и отвечать на них осмысленно.

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