WhatsApp MCP(Model Context Protocol) 서버는 macOS에서 WhatsApp 데스크톱 애플리케이션과 프로그래밍 방식으로 상호 작용할 수 있도록 하는 Node.js 애플리케이션입니다. AppleScript 자동화를 사용하여 WhatsApp UI와 직접 상호 작용하지 않고도 메시지를 보내고 WhatsApp 상태를 확인할 수 있는 간단한 인터페이스를 제공합니다.
Related MCP server: claude-whatsapp-mcp
WhatsApp 연락처 목록에 있는 특정 연락처로 문자 메시지를 보내세요.
메시지는 연결된 WhatsApp 데스크톱 애플리케이션을 통해 전달됩니다.
줄 바꿈을 포함한 메시지의 적절한 형식을 지원합니다.
AppleScript를 사용하여 WhatsApp 데스크톱 인터페이스를 자동화합니다.
현재 WhatsApp 애플리케이션이 실행 중인지 확인하세요.
WhatsApp의 현재 실행 상태를 반환합니다.
메시지를 보낼 때 오류를 방지하는 데 도움이 됩니다.
WhatsApp의 개인정보 보호로 인해 이 기능은 제한된 기능을 제공합니다.
WhatsApp의 개인정보 보호 제한 사항에 대해 사용자에게 알립니다.
메시지 전송을 위해 정확한 연락처 이름이 필요합니다.
@modelcontextprotocol/sdk - MCP 서버 및 stdio 전송
Zod - 스키마 검증
Node.js 내장 모듈(child_process, util, fs)
macOS 자동화를 위한 AppleScript
표준화된 도구 통신을 위해 MCP(Model Context Protocol)를 사용합니다.
통신을 위해 stdio 전송을 사용합니다.
WhatsApp 데스크톱 애플리케이션과 상호 작용하기 위해 AppleScript 명령을 실행합니다.
디버깅을 위한 포괄적인 오류 로깅을 구현합니다.
macOS 운영 체제
WhatsApp 데스크톱 애플리케이션 설치됨
Node.js v14.0.0 이상
인터넷 연결
지엑스피1
node index.jsClaude가 WhatsApp MCP 서버를 사용할 수 있도록 하려면 다음 단계를 따르세요.
MCP 서버 설정
위에 설명된 대로 WhatsApp MCP 서버를 설치하고 구성하세요.
로컬 컴퓨터에서 서버가 제대로 실행되고 있는지 확인하세요.
MCP 도구로 Claude Desktop 구성
WhatsApp MCP 도구를 포함하도록 claude_desktop_config.json 파일을 수정하세요.
이 파일은 일반적으로 Claude Desktop 애플리케이션 구성 디렉토리에 있습니다.
WhatsApp MCP 도구를 등록하려면 다음 구성을 추가하세요.
{
"mcpServers": [
{
"name": "whatsapp-mcp",
"transport": {
"command": "node",
"args": ["path/to/your/index.js"]
}
}
]
}통합 테스트
Claude와 테스트 대화를 만들어 보세요
Claude에게 테스트 연락처로 WhatsApp 메시지를 보내도록 요청하세요.
WhatsApp 데스크톱 앱을 통해 메시지가 성공적으로 전송되었는지 확인하세요.
지정된 WhatsApp 연락처로 메시지를 보냅니다.
매개변수:
contactName : WhatsApp에 표시되는 연락처의 전체 이름
message : 보낼 메시지의 내용
사용 예(MCP 클라이언트를 통해):
const response = await client.invoke("send-whatsapp-message", {
contactName: "John Doe",
message: "Hello, how are you today?"
});현재 WhatsApp 애플리케이션이 실행 중인지 확인합니다.
매개변수가 필요하지 않습니다.
사용 예(MCP 클라이언트를 통해):
const response = await client.invoke("check-whatsapp-status", {});연락처 목록에 대한 WhatsApp의 개인정보 보호 제한에 대한 정보를 제공합니다.
매개변수가 필요하지 않습니다.
사용 예(MCP 클라이언트를 통해):
const response = await client.invoke("list-recent-contacts", {});서버는 AppleScript를 사용하여 WhatsApp 데스크톱 애플리케이션을 자동화합니다.
WhatsApp 애플리케이션을 활성화합니다
키보드 단축키를 사용하여 인터페이스를 탐색합니다.
이름으로 연락처 검색
아래쪽 화살표 탐색을 사용하여 연락처를 선택합니다.
메시지를 입력하고 보냅니다
포괄적인 오류 처리 및 로깅:
콘솔 오류 출력
~/Library/Logs/whatsapp-mcp/ 의 파일 기반 로깅
AppleScript 실행 오류의 우아한 처리
프로세스 수준 예외 처리
Claude와 WhatsApp MCP 도구를 통합하면 자연어를 사용하여 Claude에게 다음 작업을 지시할 수 있습니다.
예시 프롬프트:
"존에게 WhatsApp 메시지를 보내서 회의에 10분 늦을 거라고 말해줘"
"다음 텍스트를 WhatsApp으로 Sarah에게 보내세요: 요청하신 문서입니다"
"엄마에게 왓츠앱으로 '생일 축하해!'를 보내세요"
예시 프롬프트:
"내 컴퓨터에서 WhatsApp이 실행되고 있나요?"
"WhatsApp이 활성화되어 있는지 확인하세요"
"메시지를 보내기 전에 WhatsApp 상태를 확인하세요"
예시 프롬프트:
"최근 WhatsApp 연락처 목록을 알려주시겠어요?"
"최근 WhatsApp에서 누구에게 메시지를 보냈는지 보여줘"
클로드는 귀하의 요청에 따라 적절한 MCP 도구를 사용하고 결과에 대한 피드백을 제공합니다.
AppleScript 종속성으로 인해 macOS에서만 작동합니다.
WhatsApp 데스크톱 애플리케이션을 설치해야 합니다.
WhatsApp UI 변경으로 인해 연락처 선택에 영향을 미칠 수 있습니다.
개인정보 보호로 인해 WhatsApp 연락처 목록에 대한 액세스가 제한됨
로컬 MCP 도구에 액세스하려면 Claude를 적절하게 구성해야 합니다.
서버는 귀하의 개인 WhatsApp 계정과 상호 작용합니다.
메시지는 귀하의 계정에서 전송되며 귀하가 보낸 것으로 표시됩니다.
신뢰할 수 있는 환경에서만 사용하세요
MIT
이 프로젝트는 WhatsApp Inc. 또는 Meta Platforms, Inc.와 제휴 관계가 없습니다. 사용자의 재량에 따라 WhatsApp의 서비스 약관을 준수하여 사용하세요.
Check if WhatsApp is currently running
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool checks if WhatsApp is 'currently running,' which implies a read-only operation, but doesn't disclose behavioral traits like what 'running' means (e.g., process active, logged in), error handling, or performance characteristics. The description is minimal and lacks context beyond the basic purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that directly states the tool's purpose without any wasted words. It is appropriately sized and front-loaded, making it easy to understand at a glance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no annotations, no output schema), the description is minimally adequate. It covers the basic purpose but lacks details on behavior, output format, or usage context, which could be helpful for an agent to understand what 'running' entails or how to interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add parameter details, which is appropriate here, and it doesn't contradict the schema. Baseline is 4 for tools with no parameters, as there's nothing to compensate for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Check if') and resource ('WhatsApp'), specifying what the tool does. It distinguishes from siblings like 'send-whatsapp-message' by focusing on status checking rather than messaging, though it doesn't explicitly mention the sibling 'list-recent-contacts'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description implies usage for checking WhatsApp's operational status, but it doesn't specify scenarios, prerequisites, or exclusions, such as whether it requires WhatsApp to be installed or configured.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recently contacted people on WhatsApp (simplified)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states it lists contacts but doesn't explain what 'recently contacted' means (timeframe, criteria), how results are ordered, or any limitations (e.g., pagination, rate limits). The 'simplified' hint is insufficient to convey operational behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words. It's front-loaded with the core purpose ('List recently contacted people on WhatsApp') and uses a brief qualifier ('simplified') that, while vague, doesn't detract from clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is incomplete. It lacks details on what 'recently contacted' entails, how results are returned, or any behavioral constraints. For a tool that presumably returns data, more context on output format or limitations is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, focusing instead on the tool's purpose. Baseline is 4 for zero-parameter tools when schema coverage is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and target resource ('recently contacted people on WhatsApp'), making the purpose understandable. It distinguishes from siblings by focusing on listing contacts rather than checking status or sending messages. However, the qualifier 'simplified' is vague and doesn't specify what makes it simplified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (WhatsApp contacts) but provides no explicit guidance on when to use this tool versus alternatives. No prerequisites, exclusions, or comparisons to sibling tools are mentioned, leaving the agent to infer usage from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a message to a contact on WhatsApp
| Name | Required | Description | Default |
|---|---|---|---|
| contactName | Yes | Full name of the contact as it appears in WhatsApp | |
| message | Yes | Message content to send |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action but fails to mention critical traits like authentication needs, rate limits, error handling, or whether the message is sent immediately or queued. This leaves significant gaps in understanding the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's function without any unnecessary words. It is front-loaded and appropriately sized for a simple tool, making it easy to grasp quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It doesn't address behavioral aspects like success/error responses, side effects, or integration with sibling tools. For a messaging tool with potential complexities, more context is needed to ensure proper usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with clear descriptions for both parameters ('contactName' and 'message'). The description adds no additional meaning beyond the schema, such as formatting details or examples, but the schema adequately documents the parameters, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Send a message') and target ('to a contact on WhatsApp'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'check-whatsapp-status' or 'list-recent-contacts' beyond the obvious functional difference, missing explicit distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives or any prerequisites. The description lacks context about usage scenarios, such as when to choose this over other messaging methods or if there are limitations like contact availability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0check-whatsapp-status1 field changedInput schema / additionalPropertiesRemoved value: -falselist-recent-contacts1 field changedInput schema / additionalPropertiesRemoved value: -falsecheck-whatsapp-statuslist-recent-contactssend-whatsapp-messageScored across 3 tools
Each tool has a clearly distinct purpose: checking WhatsApp status, listing recent contacts, and sending messages. There is no overlap in functionality, making it easy for an agent to select the correct tool without confusion.
The tools follow a consistent verb-noun pattern with hyphens (e.g., check-whatsapp-status, list-recent-contacts, send-whatsapp-message). However, the use of hyphens instead of underscores is a minor deviation from common snake_case conventions, but it remains readable and predictable.
With only 3 tools, the server feels thin for managing WhatsApp interactions, as it lacks operations like reading messages, managing groups, or handling media. While the tools cover basic actions, the scope is limited, making it borderline appropriate for a comprehensive WhatsApp integration.
The toolset is significantly incomplete for a WhatsApp server, missing essential CRUD operations such as reading incoming messages, replying to messages, managing contacts or groups, and handling attachments. This will likely cause agent failures when trying to perform common WhatsApp tasks beyond the basic ones provided.
MCP connector for iMessage & Contacts via a local Mac agent + Vercel relay
Send WhatsApp messages from your own number, read the replies and send login codes.
I send and manage WhatsApp Web messages through your linked session
Your own WhatsApp as an MCP server: read, search and send from any MCP client.