Evolution API

You run an MCP server that exposes Evolution API functionality for sending WhatsApp messages, checking numbers, and managing contacts, groups, and chats. This server acts as a bridge between your local MCP client and the Evolution API, enabling reliable messaging workflows and status checks from your applications.

How to use

Connect to the Evolution API MCP server using an HTTP MCP URL. With a client, you can perform common operations such as checking server health, listing your instances, querying instance status, sending text messages, verifying phone numbers, and enumerating contacts, groups, and chats. Use the API key header for authentication and pass the appropriate JSON payloads for actions like sending messages or checking numbers.

How to install

Prerequisites: Node.js is recommended for MCP server tooling and client libraries. Ensure you have a modern Node.js version installed.

1. Install dependencies for your MCP client project.

2. Configure the MCP client to point to your Evolution API MCP server URL and provide the API key in headers.

3. Run your client or scripts that interact with the MCP server to perform actions like sending messages or checking numbers.

Configuration and usage notes

HTTP MCP server URL: https://mcp-evolution-api-fixed-production.up.railway.app/ (this is the remote MCP endpoint you connect to).

API key usage: Include the header X-API-Key with the value corresponding to your authorized key, e.g. X-API-Key: YOUR_API_KEY for requests that require authentication.

Environment variables shown for the MCP server deployment include the Evolution API URL, API key placeholder, MCP server port, and node environment. It is important to keep the API key secure and not expose it in client-side code. Use placeholders where appropriate in example configurations.

If the Evolution API or the MCP server experiences issues, review health, connectivity, and startup logs, and ensure the server is reachable at the designated URL.

Troubleshooting

The message may fail to reach WhatsApp if the instance is not connected. Check that the instance state is open or connected; if not, rescan the QR code to re-establish the session.

Number formatting for Brazil should be 55 + area code + number with no spaces or symbols (for example, 554198908495). Do not include a leading +.

To verify WhatsApp availability for numbers, use the check-numbers endpoint to confirm each number has WhatsApp associated.

If you see an Access denied error, verify that you are sending the header X-API-Key with the correct value. The API key must be provided in requests that require authentication.

If there is a connection issue, confirm that Evolution API is operational. You can test the Evolution API fetch endpoint to verify responsiveness.

Notes and best practices

Security: Do not expose the API key in publicly accessible code or logs. Use environment-specific configuration to inject credentials at runtime.

Rate limiting: Evolution API may enforce request limits. Design your client logic to handle retries and backoff gracefully.

WhatsApp session management: The WhatsApp session may expire and require scanning a new QR code to reauthenticate.

Number handling: Ensure phone numbers are formatted correctly for the target country and do not include symbols beyond the country code and digits.

Example commands you will use with the MCP server

# Check server info
curl https://mcp-evolution-api-fixed-production.up.railway.app/

# Check server health
curl https://mcp-evolution-api-fixed-production.up.railway.app/api/health \
  -H "X-API-Key: YOUR_API_KEY"

# List instances
curl https://mcp-evolution-api-fixed-production.up.railway.app/api/instances \
  -H "X-API-Key: YOUR_API_KEY"

# Send a text message
curl -X POST https://mcp-evolution-api-fixed-production.up.railway.app/api/send/text \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"instanceName": "Luis2", "number": "554198908495", "text": "Hello" }'
```}]},

Server configuration and environment

The Evolution API MCP server is exposed via HTTP at the following URL: https://mcp-evolution-api-fixed-production.up.railway.app/. The Evolution API URL used by the server is https://evolution-api-evolution-api.dqyvuv.easypanel.host. The server uses port 3000 in production mode.

Environment variables in the deployment include the Evolution API URL, API key placeholder, server port, and node environment. Keep sensitive values secure and inject them at runtime.

Available tools

getServerInfo

Fetch basic server information including version and capabilities.

healthCheck

Check the health status of the MCP server and backend integrations.

listInstances

Retrieve a list of MCP instances configured for this server.

instanceStatus

Query the status of a specific instance, e.g., open/connected.

sendText

Send a text message to a specified WhatsApp number via a chosen instance.

checkNumbers

Verify whether the provided numbers have WhatsApp active accounts.

listContacts

List contacts associated with a given instance.

listGroups

List groups associated with a given instance.

listChats

List chats associated with a given instance.