Skip to content

Commit 6aa23e3

Browse files
lightaimelightaime
authored
feat: Add WhatsApp MCP integration use case for OWL (camel-ai#477)
2 parents b29f1e4 + c0232e6 commit 6aa23e3

3 files changed

Lines changed: 392 additions & 0 deletions

File tree

‎community_usecase/Whatsapp-MCP/README.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
# OWL WhatsApp MCP Integration
2+
3+
This project demonstrates a use case connecting **OWL** (from [CAMEL-AI.org](https://camel-ai.org)) with the **WhatsApp MCP Server**. It enables fully automated, agentic replies within messaging apps—without needing predefined workflows or manual tool selection. Simply send a plain message and let the system handle the rest.
4+
5+
---
6+
7+
## Overview
8+
9+
### What It Does
10+
11+
- **Automated, Agentic Messaging:**
12+
OWL interacts with the WhatsApp MCP server in real time. Roleplay agents infer the intent behind your messages, automatically selecting the correct toolkit to generate and send responses.
13+
14+
- **Seamless Communication Integration:**
15+
This integration demonstrates how intelligent agents can operate across different communication platforms with zero manual orchestration.
16+
17+
### Key Features
18+
19+
- **No Predefined Workflow:**
20+
No need for rigid, pre-set procedures. The system dynamically handles each conversation.
21+
22+
- **Zero Tool Selection Required:**
23+
Simply send a message; the right toolkit is autonomously selected based on the agent’s inference.
24+
25+
- **Real-Time Interaction:**
26+
OWL continuously communicates with the WhatsApp MCP server to access message histories, send replies, and manage media files.
27+
28+
---
29+
30+
## Technology Stack
31+
32+
- **OWL Framework:**
33+
An open-source multi-agent collaboration framework from [CAMEL-AI](https://github.com/camel-ai/owl).
34+
- **WhatsApp MCP Server:**
35+
An MCP (Model Context Protocol) server that connects directly to WhatsApp via the WhatsApp Web multi-device API. Explore the project on [GitHub](https://github.com/lharries/whatsapp-mcp).
36+
37+
---
38+
39+
## How It Works
40+
41+
1. **Message Processing:**
42+
- A plain text message is sent by a user via a messaging app.
43+
- The OWL framework receives the message and activates roleplay agents.
44+
45+
2. **Agent Collaboration:**
46+
- Agents, acting in different roles, infer the intent and formulate a response.
47+
- The appropriate toolkit is dynamically selected.
48+
49+
3. **Automated Reply:**
50+
- The system communicates in real time with the WhatsApp MCP server.
51+
- The response is generated and sent back to the messaging app autonomously.
52+
53+
---
54+
55+
## Getting Started
56+
57+
### Prerequisites
58+
59+
- **Go:** Required for the WhatsApp Bridge component.
60+
- **Python 3.6+:** For running the MCP server and OWL integration.
61+
- **UV Package Manager:** Install with:
62+
```sh
63+
curl -LsSf https://astral.sh/uv/install.sh | sh
64+
```
65+
- **FFmpeg (Optional):** Needed for converting and sending audio messages in the correct format (e.g., .ogg Opus).
66+
67+
### Installation Steps
68+
69+
1. **Clone Repositories:**
70+
- OWL Framework:
71+
```sh
72+
git clone https://github.com/camel-ai/owl.git
73+
```
74+
- WhatsApp MCP Server:
75+
```sh
76+
git clone https://github.com/lharries/whatsapp-mcp.git
77+
```
78+
79+
2. **Set Up the WhatsApp Bridge:**
80+
- Navigate to the WhatsApp bridge directory:
81+
```sh
82+
cd whatsapp-mcp/whatsapp-bridge
83+
go run main.go
84+
```
85+
- **Authentication:**
86+
On first run, scan the provided QR code using your WhatsApp app. (Re-authentication may be required after ~20 days.)
87+
88+
3. **Configure MCP Server Integration:**
89+
- Create a JSON configuration file (e.g., `claude_desktop_config.json` or `mcp.json`) with the following content (ensure you replace the placeholder paths):
90+
```json
91+
{
92+
"mcpServers": {
93+
"whatsapp": {
94+
"command": "<PATH_TO_UV>",
95+
"args": [
96+
"--directory",
97+
"<PATH_TO_REPO>/whatsapp-mcp/whatsapp-mcp-server",
98+
"run",
99+
"main.py"
100+
]
101+
}
102+
}
103+
}
104+
```
105+
- Place this file in your Claude Desktop configuration directory or your Cursor configuration directory as appropriate.
106+
107+
4. **Running the OWL MCP Integration:**
108+
- With the WhatsApp Bridge running and MCP configuration set up, start your OWL-powered agent system:
109+
```sh
110+
python owl/community_usecase/Whatsapp-MCP/app.py
111+
```
112+
- The OWL framework will connect to the MCP server and be ready to process incoming messages.
113+
114+
---
115+
116+
## Deep Dive: MCP & OWL Integration
117+
118+
### MCP Overview
119+
- **What is MCP?**
120+
MCP (Model Context Protocol) standardizes communication between AI models and external tools and data sources. Learn more at the [MCP Documentation](https://modelcontextprotocol.io/introduction).
121+
122+
- **Basic Architecture:**
123+
MCP uses a client-server model, where a host application communicates with multiple MCP servers to seamlessly access local and remote data sources.
124+
125+
### OWL Framework
126+
- **Role-Playing Agents:**
127+
OWL leverages roleplay agents that deconstruct tasks and work collaboratively, ensuring robust automation.
128+
129+
- **Real-Time Decision-Making:**
130+
Using methods such as POMDP (Partially Observable Markov Decision Processes), OWL optimizes decisions dynamically.
131+
132+
- **Multi-Modal Tool Integration:**
133+
From web data scraping to code execution and document processing, OWL integrates various toolkits to empower agent collaboration.
134+
135+
### Code Example Snippet
136+
137+
Below is a simplified version of how to initialize and connect to the MCP toolkit:
138+
139+
```python
140+
from pathlib import Path
141+
from mcp_toolkit import MCPToolkit
142+
143+
# Load configuration and initialize MCP toolkit
144+
config_path = Path(__file__).parent / "mcp_servers_config.json"
145+
mcp_toolkit = MCPToolkit(config_path=str(config_path))
146+
147+
# Establish asynchronous connection
148+
await mcp_toolkit.connect()
149+
```
150+
151+
Then, construct the agent environment and run the task:
152+
153+
```python
154+
question = (
155+
"I'd like an academic report about Andrew Ng, including his research direction, "
156+
"published papers, and affiliated institutions. Organize the report in Markdown format and save it to my desktop."
157+
)
158+
tools = list(mcp_toolkit.get_tools())
159+
society = await construct_society(question, tools)
160+
answer, chat_history, token_count = await run_society(society)
161+
print(f"Answer: {answer}")
162+
```
163+
164+
For a complete guide on using MCP with the OWL framework, please refer to [the detailed guide](https://www.camel-ai.org/blogs/owl-mcp-toolkit-practice).
165+
166+
---
167+
168+
## WhatsApp MCP Server Details
169+
170+
- **Capabilities:**
171+
- **Message Management:** Search, read, and send messages including media (images, videos, documents, audio).
172+
- **Media Handling:** Supports conversion (with FFmpeg) and downloading of media files.
173+
174+
- **Architecture:**
175+
- **Go WhatsApp Bridge:** Connects to WhatsApp’s Web API, handles QR code authentication, and stores messages locally using SQLite.
176+
- **Python MCP Server:** Implements the MCP protocol to relay communications between OWL agents and WhatsApp.
177+
178+
- **Installation & Running:**
179+
- Follow the instructions under the **Installation Steps** section above.
180+
- Additional details and troubleshooting tips are available in the [WhatsApp MCP GitHub repository](https://github.com/lharries/whatsapp-mcp).
181+
182+
---
183+
184+
## Troubleshooting & FAQs
185+
186+
- **QR Code Not Displaying:**
187+
Ensure your terminal supports displaying QR codes, or try restarting the authentication script.
188+
189+
- **Device Limit Issues:**
190+
If you reach the maximum number of devices on WhatsApp, remove an existing device from your phone’s linked devices settings.
191+
192+
- **Running on Windows:**
193+
For Windows setups, ensure that CGO is enabled and a C compiler (e.g., through MSYS2) is installed. See the [Windows Compatibility Guide](#) for step-by-step instructions.
194+
195+
---
196+
197+
## References & Further Reading
198+
199+
- **MCP Documentation:** [modelcontextprotocol.io](https://modelcontextprotocol.io/introduction)
200+
- **CAMEL-AI MCP:** [camel-ai.org/mcp](https://www.camel-ai.org/mcp)
201+
- **WhatsApp MCP Server Repository:** [GitHub](https://github.com/lharries/whatsapp-mcp)
202+
- **OWL Framework Repository:** [GitHub](https://github.com/camel-ai/owl)
203+
204+
---
205+
206+
207+

‎community_usecase/Whatsapp-MCP/app.py‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
2+
# Licensed under the Apache License, Version 2.0 (the "License");
3+
# you may not use this file except in compliance with the License.
4+
# You may obtain a copy of the License at
5+
#
6+
# http://www.apache.org/licenses/LICENSE-2.0
7+
#
8+
# Unless required by applicable law or agreed to in writing, software
9+
# distributed under the License is distributed on an "AS IS" BASIS,
10+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11+
# See the License for the specific language governing permissions and
12+
# limitations under the License.
13+
# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
14+
"""MCP Multi-Agent System Example
15+
16+
This example demonstrates how to use MCP (Model Context Protocol) with CAMEL agents
17+
for advanced information retrieval and processing tasks.
18+
19+
Environment Setup:
20+
1. Configure the required dependencies of owl library
21+
Refer to: https://github.com/camel-ai/owl for installation guide
22+
23+
2. MCP Server Setup:
24+
25+
26+
2.1 MCP Playwright Service:
27+
```bash
28+
# Install MCP service
29+
npm install -g @executeautomation/playwright-mcp-server
30+
npx playwright install-deps
31+
32+
# Configure in mcp_servers_config.json:
33+
{
34+
"mcpServers": {
35+
"playwright": {
36+
"command": "npx",
37+
"args": ["-y", "@executeautomation/playwright-mcp-server"]
38+
}
39+
}
40+
}
41+
```
42+
43+
2.2 MCP Fetch Service (Optional - for better retrieval):
44+
```bash
45+
# Install MCP service
46+
pip install mcp-server-fetch
47+
48+
# Configure in mcp_servers_config.json:
49+
{
50+
"mcpServers": {
51+
"fetch": {
52+
"command": "python",
53+
"args": ["-m", "mcp_server_fetch"]
54+
}
55+
}
56+
}
57+
```
58+
59+
Usage:
60+
1. Ensure all MCP servers are properly configured in mcp_servers_config.json
61+
2. Run this script to create a multi-agent system that can:
62+
- Access and manipulate files through MCP Desktop Commander
63+
- Perform web automation tasks using Playwright
64+
- Process and generate information using GPT-4o
65+
- Fetch web content (if fetch service is configured)
66+
3. The system will execute the specified task while maintaining security through
67+
controlled access
68+
69+
Note:
70+
- All file operations are restricted to configured directories
71+
- System uses GPT-4o for both user and assistant roles
72+
- Supports asynchronous operations for efficient processing
73+
"""
74+
75+
import asyncio
76+
import sys
77+
from pathlib import Path
78+
from typing import List
79+
80+
from dotenv import load_dotenv
81+
82+
from camel.models import ModelFactory
83+
from camel.toolkits import FunctionTool
84+
from camel.types import ModelPlatformType, ModelType
85+
from camel.logger import set_log_level
86+
from camel.toolkits import MCPToolkit,SearchToolkit
87+
88+
from owl.utils.enhanced_role_playing import OwlRolePlaying, arun_society
89+
90+
load_dotenv()
91+
92+
set_log_level(level="DEBUG")
93+
94+
95+
async def construct_society(
96+
question: str,
97+
tools: List[FunctionTool],
98+
) -> OwlRolePlaying:
99+
r"""build a multi-agent OwlRolePlaying instance.
100+
101+
Args:
102+
question (str): The question to ask.
103+
tools (List[FunctionTool]): The MCP tools to use.
104+
"""
105+
models = {
106+
"user": ModelFactory.create(
107+
model_platform=ModelPlatformType.OPENAI,
108+
model_type=ModelType.GPT_4O,
109+
model_config_dict={"temperature": 0},
110+
),
111+
"assistant": ModelFactory.create(
112+
model_platform=ModelPlatformType.OPENAI,
113+
model_type=ModelType.GPT_4O,
114+
model_config_dict={"temperature": 0},
115+
),
116+
}
117+
118+
user_agent_kwargs = {"model": models["user"]}
119+
assistant_agent_kwargs = {
120+
"model": models["assistant"],
121+
"tools": tools,
122+
}
123+
124+
task_kwargs = {
125+
"task_prompt": question,
126+
"with_task_specify": False,
127+
}
128+
129+
society = OwlRolePlaying(
130+
**task_kwargs,
131+
user_role_name="user",
132+
user_agent_kwargs=user_agent_kwargs,
133+
assistant_role_name="assistant",
134+
assistant_agent_kwargs=assistant_agent_kwargs,
135+
)
136+
return society
137+
138+
139+
async def main():
140+
config_path = Path(__file__).parent / "mcp_servers_config.json"
141+
mcp_toolkit = MCPToolkit(config_path=str(config_path))
142+
143+
try:
144+
print("Attempting to connect to MCP servers...")
145+
await mcp_toolkit.connect()
146+
147+
# Default task
148+
default_task = (
149+
"Read the unread messages from {contact name} on whatsapp and reply to his query"
150+
)
151+
152+
# Override default task if command line argument is provided
153+
task = sys.argv[1] if len(sys.argv) > 1 else default_task
154+
# Connect to all MCP toolkits
155+
tools = [*mcp_toolkit.get_tools(),SearchToolkit().search_duckduckgo,]
156+
society = await construct_society(task, tools)
157+
answer, chat_history, token_count = await arun_society(society)
158+
print(f"\033[94mAnswer: {answer}\033[0m")
159+
160+
except Exception as e:
161+
print(f"An error occurred during connection: {e}")
162+
163+
finally:
164+
# Make sure to disconnect safely after all operations are completed.
165+
try:
166+
await mcp_toolkit.disconnect()
167+
except Exception:
168+
print("Disconnect failed")
169+
170+
171+
if __name__ == "__main__":
172+
asyncio.run(main())

‎community_usecase/Whatsapp-MCP/mcp_servers_config.json‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"mcpServers": {
3+
"whatsapp": {
4+
"command": "{{PATH_TO_UV}}",
5+
"args": [
6+
"--directory",
7+
"{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server",
8+
"run",
9+
"main.py"
10+
]
11+
}
12+
}
13+
}

0 commit comments

Comments
 (0)