WhatsApp Claude MCP

Мощный WhatsApp-бот, интегрированный с Claude AI с использованием Model Context Protocol (MCP). Отправляйте сообщения вашему WhatsApp-боту и получайте интеллектуальные ответы от Claude, с доступом к внешним API и инструментам.

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

• Интеграция Claude AI: использует Claude 3.5 Sonnet для интеллектуальных бесед

• Инструменты MCP: расширяемая система инструментов для взаимодействия Claude с внешними API

• Генератор шуток: встроенный инструмент, который получает случайные шутки из внешнего API

• Память переписки: сохраняет контекст между несколькими сообщениями для каждого пользователя

• Вебхук WhatsApp: простой REST API для интеграции с сервисами WhatsApp

• Простое развертывание: работает с Express-сервером, готов к облачному развертыванию

Related MCP server: WAHA WhatsApp MCP Server

📋 Предварительные требования

• Node.js 18+

• npm или yarn

• Anthropic API-ключ (получите на console.anthropic.com)

• Доступ к WhatsApp Cloud API (для производственной интеграции)

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

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

git clone https://github.com/yulianheroes-lgtm/whatsapp-claude-mcp.git
cd whatsapp-claude-mcp
npm install

2. Настройка переменных окружения

cp .env.example .env

Отредактируйте .env и добавьте ваш Anthropic API-ключ:

ANTHROPIC_API_KEY=your_anthropic_api_key_here
PORT=3000

3. Запуск сервера

npm start

Вы должны увидеть:

✅ WhatsApp Claude MCP Server running on http://localhost:3000
🤖 Ready to process WhatsApp messages!

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

Проверка здоровья

curl http://localhost:3000/health

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

curl -X POST http://localhost:3000/webhook/whatsapp \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "1234567890",
    "message": "Tell me a joke"
  }'

Ответ:

{
  "success": true,
  "userId": "1234567890",
  "message": "😂 Here's a programming joke for you!\n\nWhy do programmers prefer dark mode?\n\nBecause light attracts bugs! 🐛"
}

Очистка истории переписки

curl -X POST http://localhost:3000/webhook/clear-history \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "1234567890"
  }'

🛠️ Доступные инструменты

Генератор шуток

Claude может автоматически использовать этот инструмент, когда это уместно:

• Триггер: когда пользователь просит шутки

• Типы: random, programming, general

• API: Official Joke API

Пример взаимодействия:

User: Tell me a funny programming joke
Bot: [Uses joke_generator tool] 😂 Here's a programming joke...

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

whatsapp-claude-mcp/
├── src/
│   ├── index.js              # Main Express server
│   ├── whatsapp-handler.js   # Message handling & Claude integration
│   ├── mcp-server.js         # MCP tool definitions & execution
│   └── tools/
│       └── joke-generator.js # Joke generator tool implementation
├── .env.example              # Environment variables template
├── .gitignore               # Git ignore rules
├── package.json             # Dependencies
└── README.md                # This file

🔌 Интеграция с WhatsApp

Вариант 1: WhatsApp Cloud API

Для продакшена интегрируйте WhatsApp Cloud API:

1. Настройте вебхук на Meta Business Platform

2. Укажите URL вебхука: https://your-domain.com/webhook/whatsapp

3. Когда WhatsApp отправляет сообщения, перенаправляйте их на этот endpoint

Вариант 2: Локальное тестирование

Используйте такие инструменты, как curl, Postman или тестовый скрипт, для отправки сообщений:

// test.js
const userId = '1234567890';
const message = 'Tell me a joke';

const response = await fetch('http://localhost:3000/webhook/whatsapp', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ userId, message })
});

const result = await response.json();
console.log(result.message);

🧠 Как это работает

1. Сообщение получено → вебхук WhatsApp получает сообщение

2. Обработка Claude → сообщение отправляется в Claude с доступными инструментами

3. Выбор инструмента → Claude решает, нужны ли инструменты

4. Выполнение инструмента → MCP-сервер выполняет инструменты (например, получение шуток)

5. Генерация ответа → Claude генерирует ответ, используя результаты инструментов

6. Отправка сообщения → ответ отправляется обратно через WhatsApp

🚀 Добавление новых инструментов

Чтобы добавить новый инструмент (например, погоду, переводы):

1. Создайте файл инструмента

// src/tools/weather.js
export const weatherTool = {
  name: 'get_weather',
  description: 'Get current weather for a location',
  inputSchema: {
    type: 'object',
    properties: {
      location: { type: 'string', description: 'City name' }
    }
  }
};

export async function executeWeather(location) {
  // Fetch weather data
  return { /* weather data */ };
}

2. Зарегистрируйте в MCP-сервере

// src/mcp-server.js
import { weatherTool, executeWeather } from './tools/weather.js';

export class MCPServer {
  constructor() {
    this.tools = [
      jokeGeneratorTool,
      weatherTool  // Add here
    ];
  }

  async processTool(toolName, toolInput) {
    switch (toolName) {
      case 'get_weather':
        return await executeWeather(toolInput.location);
      // ...
    }
  }
}

📚 Справочник по API

POST /webhook/whatsapp

Тело запроса:

{
  "userId": "string (required)",
  "message": "string (required)"
}

Ответ:

{
  "success": boolean,
  "userId": "string",
  "message": "string"
}

POST /webhook/clear-history

Тело запроса:

{
  "userId": "string (required)"
}

Ответ:

{
  "success": boolean,
  "message": "string"
}

🔐 Вопросы безопасности

• API-ключи: никогда не коммитьте файл .env в систему контроля версий

• Ограничение частоты запросов: рассмотрите возможность добавления rate limiting для продакшена

• Валидация входных данных: всегда проверяйте полезную нагрузку вебхуков

• HTTPS: используйте HTTPS в продакшене

• Аутентификация: добавьте проверку подписи вебхука для интеграции WhatsApp

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

🤝 Вклад в проект

Не стесняйтесь форкать, модифицировать и делать свой вклад!

📄 Лицензия

Лицензия MIT — подробности в файле LICENSE

🆘 Поиск и устранение проблем

«API-ключ не найден»

• Убедитесь, что файл .env существует и содержит ANTHROPIC_API_KEY

• Проверьте ключ на console.anthropic.com

«Не удалось выполнить инструмент»

• Проверьте доступность внешних API

• Проверьте сетевое подключение

• Просмотрите логи ошибок в выводе консоли

«Нет ответа от Claude»

• Убедитесь, что ANTHROPIC_API_KEY указан верно

• Убедитесь, что модель Claude доступна

• Проверьте ограничения частоты запросов к API

📞 Поддержка

По вопросам и проблемам:

1. Ознакомьтесь с разделом поиска и устранения проблем

2. Изучите документацию Claude API

3. Откройте issue на GitHub

🎯 Планируемые улучшения

• Поддержка изображений/медиа в сообщениях WhatsApp

• Дополнительные инструменты (погода, новости, переводы)

• База данных для постоянной истории переписки

• Ограничение частоты запросов и аутентификация

• Административная панель для мониторинга

• Многоязычная поддержка

• Индивидуальные системные промпты Claude для каждого пользователя

Сделано с ❤️ by yulianheroes-lgtm