# Waalaxy MCP Server

MCP (Model Context Protocol) server for [Waalaxy](https://www.waalaxy.com/) - LinkedIn automation tool.

## ⚠️ Status: In Development

Waalaxy does not provide a public API. This MCP server uses browser automation (Playwright) to interact with the Waalaxy web interface.

## Features (Planned)

| Tool | Description | Status |
|------|-------------|--------|
| `get_campaigns` | List all campaigns | 🔄 Planned |
| `get_campaign_stats` | Get campaign statistics | 🔄 Planned |
| `get_prospects` | List prospects in a campaign | 🔄 Planned |
| `get_conversations` | Get LinkedIn conversations | 🔄 Planned |
| `create_campaign` | Create a new campaign | 🔄 Planned |
| `add_prospects` | Add prospects to a campaign | 🔄 Planned |
| `send_message` | Send a message to a prospect | 🔄 Planned |
| `get_analytics` | Get account analytics | 🔄 Planned |

## Prerequisites

- Python 3.10+
- [uv](https://docs.astral.sh/uv/) package manager
- Playwright with Chromium
- Active Waalaxy account

## Installation

```bash
# Install dependencies
uv sync

# Install Playwright browsers
uvx playwright install chromium

# Create session (first time)
uvx mcp-server-waalaxy --get-session
```

## Configuration

```json
{
  "mcpServers": {
    "waalaxy": {
      "command": "uvx",
      "args": ["mcp-server-waalaxy"]
    }
  }
}
```

## Session Management

Session is stored at `~/.waalaxy-mcp/session.json`. Re-run `--get-session` if authentication expires.

## Development

```bash
# Clone the repo
git clone https://github.com/globodai-group/mcp-server-waalaxy.git
cd mcp-server-waalaxy

# Install dev dependencies
uv sync --dev

# Run tests
uv run pytest
```

## Architecture

Since Waalaxy lacks a public API, this server:
1. Uses Playwright to control a headless browser
2. Authenticates via saved session cookies
3. Scrapes/interacts with the Waalaxy web app
4. Exposes functionality as MCP tools

## Related

- [linkedin-mcp-server](https://github.com/stickerdaniel/linkedin-mcp-server) - LinkedIn MCP server (similar approach)
- [Waalaxy](https://www.waalaxy.com/) - Official Waalaxy website

## License

Apache-2.0

## Contributing

PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.