VKTeams Bot MCP Server

A Model Context Protocol (MCP) server for VK Teams Bot API. Easily integrate VK Teams bots with LLM agents, automation systems, or any external service via a universal protocol.

✨ Features

• 🔄 Interactive Setup: Automatic chat ID elicitation from MCP clients
• 📤 Send Messages: Send text messages to VK Teams chats via MCP
• 📎 Enhanced File Uploads: Upload files directly from LLM with multiple formats
• 📝 Smart File Handling: Base64 upload, text-to-file, JSON uploads
• 🤖 Bot Info: Retrieve bot information and diagnostics
• 💬 Chat Management: Full chat control (members, admins, settings)
• 📁 File Operations: File uploads, voice messages, media handling
• 📡 Event Streaming: Receive chat and bot events
• 🔍 Storage Operations: Semantic search, text search, message retrieval
• 🎛️ Session Management: Reset session data and cached configurations
• 🔌 Universal Integration: Works over stdin/stdout, perfect for LLMs and automation

Quick Start

1. Set Environment Variables

export VKTEAMS_BOT_API_TOKEN=your_token_here
export VKTEAMS_BOT_API_URL=https://your-api-url
# Chat ID is now optional - will be requested interactively if needed
export VKTEAMS_BOT_CHAT_ID=your_chat_id  # Optional

2. Build and Run

cargo build --release
./target/release/vkteams-bot-mcp

3. Interactive Setup

When you first use any tool that requires a chat ID, the MCP server will automatically request it from your client:

• Chat ID: Enter your VK Teams chat ID (e.g., 751987654321@chat.agent)
• The chat ID will be cached for the current session
• Use reset_session tool to clear cached data

4. Example MCP Requests

Send a text message (chat ID requested automatically)

{
  "tool": "send_text",
  "params": {
    "text": "Hello, world!"
  }
}

Upload a file from base64

{
  "tool": "upload_file_from_base64",
  "params": {
    "file_name": "document.txt",
    "base64_content": "SGVsbG8gV29ybGQh",
    "caption": "Here's the document you requested"
  }
}

Upload text as a file

{
  "tool": "upload_text_as_file",
  "params": {
    "file_name": "script.py",
    "content": "print('Hello from Python!')",
    "caption": "Python script generated by AI"
  }
}

Reset session (clear cached chat ID)

{
  "tool": "reset_session",
  "params": {}
}

Usage

The server communicates via the MCP protocol over standard input/output. You can connect it to LLM agents, automation scripts, or use it as a standalone service.

Supported Tools

Core Bot Operations

• self_get — Get bot information and status
• file_info — Get file information and metadata
• events_get — Get events from the chat
• daemon_status — Get daemon status and statistics

Messaging Operations

• send_text — Send a text message to the chat
• send_file — Send file to chat
• send_voice — Send voice message
• edit_message — Edit existing message
• delete_message — Delete message from chat
• pin_message — Pin message in chat
• unpin_message — Unpin message in chat
• send_action — Send typing/looking indicators

File Upload Operations

• upload_file_from_base64 — Upload file from base64 encoded content
• upload_text_as_file — Create and upload text content as a file
• upload_json_file — Create and upload structured JSON files

Chat Management

• chat_info — Get chat information
• get_chat_members — Get list of chat members
• get_chat_admins — Get chat administrators
• set_chat_title — Set chat title
• set_chat_about — Set chat description

Storage Operations

• search_semantic — Search messages using semantic similarity
• search_text — Search messages using text search
• get_database_stats — Get database statistics
• get_context — Get conversation context
• get_recent_messages — Get recent messages from storage

Session Management

• reset_session — Reset session data including cached chat ID

Interactive Chat ID Configuration

The MCP server now features automatic chat ID elicitation:

How It Works

1. First Use: When you call any tool that requires a chat ID, the server automatically prompts your MCP client
2. User Input: You enter the VK Teams chat ID (e.g., 751987654321@chat.agent) in the client interface
3. Session Cache: The chat ID is stored for the entire session
4. Reset Option: Use reset_session to clear the cached chat ID and configure a new one

Benefits

• No Manual Configuration: No need to set VKTEAMS_BOT_CHAT_ID environment variable
• Session Persistence: Chat ID is remembered throughout your session
• Easy Switching: Reset and reconfigure for different chats as needed
• Client Integration: Works seamlessly with any MCP-compatible client (Claude Desktop, Continue, etc.)

File Upload Capabilities

The server includes smart file handling capabilities:

Supported Upload Methods

• Base64 Upload: Upload any file from base64 encoded content
• Text-to-File: Create text files directly from content
• JSON Upload: Create and upload structured JSON files
• Voice Messages: Send voice files (.ogg, .mp3, .wav, .m4a)

File Features

• Automatic filename handling
• Caption and reply message support
• Multiple file format support
• Safe file validation

MCP Client Compatibility

This server works with any MCP-compatible client:

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "vkteams-bot": {
      "command": "path/to/vkteams-bot-mcp",
      "env": {
        "VKTEAMS_BOT_API_TOKEN": "your_token_here",
        "VKTEAMS_BOT_API_URL": "https://your-api-url"
      }
    }
  }
}

Continue (VS Code)

Add to your config.json:

{
  "tools": [
    {
      "title": "VK Teams Bot",
      "description": "VK Teams Bot MCP Server",
      "params": {
        "command": "path/to/vkteams-bot-mcp"
      }
    }
  ]
}

Direct Integration

# Run server directly
./vkteams-bot-mcp

# Or with environment variables
VKTEAMS_BOT_API_TOKEN=token VKTEAMS_BOT_API_URL=url ./vkteams-bot-mcp

Documentation

• VK Teams Bot API
• MCP Protocol
• Claude Desktop MCP Setup