Skip to content

Commit f0f4467

Browse files
author
nmolchanov
committed
chore: initial public release
Open-source MCP gateway for the GREEN-API WhatsApp HTTP API. Provides Model Context Protocol tools, resources, and prompts so AI agents (Claude Desktop, Cursor, OpenClaw, claude.ai, etc.) can send WhatsApp messages, manage groups and contacts, and receive incoming notifications through GREEN-API. Licensed MIT — see LICENSE for details. https://green-api.com
0 parents  commit f0f4467

49 files changed

Lines changed: 10550 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
name: Bug report
3+
about: Report incorrect or unexpected behaviour
4+
labels: bug
5+
---
6+
7+
## What happened
8+
9+
<!-- A clear, concise description of the problem. -->
10+
11+
## What did you expect
12+
13+
<!-- What should have happened instead. -->
14+
15+
## Steps to reproduce
16+
17+
1.
18+
2.
19+
3.
20+
21+
## Environment
22+
23+
- Version / commit:
24+
- OS:
25+
- MCP client (Claude Desktop, OpenClaw, etc.):
26+
- Transport (`stdio` / `sse` / `http` / `hybrid`):
27+
- Auth mode (`config` / `proxy`):
28+
29+
## Logs
30+
31+
<!-- Paste relevant logs with secrets/tokens redacted. -->

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
name: Feature request
3+
about: Suggest a new tool, transport feature, or behaviour change
4+
labels: enhancement
5+
---
6+
7+
## Problem
8+
9+
<!-- What user need or use case isn't covered today. -->
10+
11+
## Proposed solution
12+
13+
<!-- How it could work. Include API/CLI shape if relevant. -->
14+
15+
## Alternatives considered
16+
17+
<!-- Other approaches you've thought about and why they're worse. -->
18+
19+
## Additional context
20+
21+
<!-- Anything else: related issues, references, prior art. -->

‎.github/workflows/ci.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
name: ci
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
8+
jobs:
9+
build:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v4
13+
14+
- uses: actions/setup-go@v5
15+
with:
16+
go-version-file: go.mod
17+
cache: true
18+
19+
- name: golangci-lint
20+
uses: golangci/golangci-lint-action@v6
21+
with:
22+
version: latest
23+
24+
- name: Test
25+
run: go test -race -cover ./...
26+
27+
- name: Build
28+
run: go build -o green-api-mcp-gateway ./cmd/server

‎.gitignore‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Binaries
2+
green-api-mcp-gateway
3+
green-api-mcp-gateway-linux
4+
*.exe
5+
6+
# Test artifacts
7+
test-all-25.py
8+
test-all-methods.py
9+
/tmp/
10+
11+
# Config with secrets
12+
config.yaml
13+
!config/config.example.yaml
14+
15+
# IDE
16+
.idea/
17+
.vscode/
18+
*.swp
19+
20+
# OS
21+
.DS_Store
22+
Thumbs.db
23+
24+

‎.golangci.yml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
version: "2"
2+
3+
linters:
4+
enable:
5+
- errcheck
6+
- govet
7+
- ineffassign
8+
- staticcheck
9+
- unused
10+
11+
formatters:
12+
enable:
13+
- gofmt
14+
- goimports

‎CONTRIBUTING.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Contributing
2+
3+
Thanks for considering a contribution to `green-api-mcp-gateway`.
4+
5+
## Quick start
6+
7+
```bash
8+
git clone https://github.com/green-api/green-api-mcp-gateway.git
9+
cd green-api-mcp-gateway
10+
make lint test build
11+
```
12+
13+
Requires Go 1.25+ and `golangci-lint`.
14+
15+
## Pull requests
16+
17+
1. Open an issue first if the change is non-trivial — it's easier to align on direction before code is written.
18+
2. Use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`).
19+
3. Keep PRs focused — one concern per PR.
20+
4. Include tests for new behaviour. Run `make test` locally before pushing.
21+
5. CI must be green before merge.
22+
23+
## Reporting issues
24+
25+
Please include:
26+
27+
- What you expected to happen
28+
- What actually happened
29+
- Steps to reproduce (minimal config / commands)
30+
- Output of `./green-api-mcp-gateway --version` (or commit SHA if built from source)
31+
- Relevant logs with secrets redacted
32+
33+
See `.github/ISSUE_TEMPLATE/` for bug-report and feature-request templates.

‎Dockerfile‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# ─── Stage 1: Build ──────────────────────────────────────────────────────────
2+
FROM golang:1.25-alpine AS builder
3+
4+
# Install git (needed for go modules from VCS)
5+
RUN apk add --no-cache git ca-certificates tzdata
6+
7+
WORKDIR /src
8+
9+
# Cache dependency downloads separately from source compilation.
10+
COPY go.mod go.sum ./
11+
RUN go mod download
12+
13+
# Copy source and build a statically-linked binary.
14+
COPY . .
15+
RUN VERSION=$(git describe --tags --always 2>/dev/null || echo "dev") && \
16+
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
17+
go build -trimpath -ldflags="-s -w -X main.version=${VERSION}" -o /app/green-api-mcp-gateway ./cmd/server
18+
19+
# ─── Stage 2: Runtime ────────────────────────────────────────────────────────
20+
FROM scratch
21+
22+
# Copy TLS certificates and timezone data from the builder stage so HTTPS
23+
# calls and time-zone-aware logging work correctly in the minimal image.
24+
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
25+
COPY --from=builder /usr/share/zoneinfo /usr/share/zoneinfo
26+
27+
# Copy the compiled binary.
28+
COPY --from=builder /app/green-api-mcp-gateway /green-api-mcp-gateway
29+
30+
# Optional: copy the example config so users can mount their own over it.
31+
COPY --from=builder /src/config/config.example.yaml /config/config.example.yaml
32+
33+
# stdio transport: the container reads from stdin / writes to stdout.
34+
# For SSE/HTTP mode expose port 8090 and optionally 8091 (webhook receiver).
35+
EXPOSE 8090 8091
36+
37+
ENTRYPOINT ["/green-api-mcp-gateway"]

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 GREEN-API
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎Makefile‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
.PHONY: lint lint-ci test build
2+
3+
lint:
4+
go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.5.0 run
5+
6+
lint-ci:
7+
go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.5.0 run
8+
9+
test:
10+
go test -v -race -count=1 ./... -coverprofile=cover.out
11+
12+
build:
13+
CGO_ENABLED=0 go build -ldflags="-s -w -X main.version=$(shell git describe --tags --always 2>/dev/null || echo dev)" -o green-api-mcp-gateway ./cmd/server

‎README-SKILL.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# GREEN-API WhatsApp Skill
2+
3+
OpenClaw skill for sending and receiving WhatsApp messages via [GREEN-API](https://green-api.com).
4+
5+
## What it does
6+
7+
Gives OpenClaw access to 35+ WhatsApp tools: messaging, file sharing, polls, contacts, groups, chat history, instance management, and more — all through the GREEN-API MCP gateway.
8+
9+
## Prerequisites
10+
11+
1. A GREEN-API account — sign up at [console.green-api.com](https://console.green-api.com)
12+
2. A created and authorized instance (with QR code or phone number)
13+
3. The GREEN-API MCP gateway server running (see below)
14+
15+
## Setup
16+
17+
### 1. Install the skill
18+
19+
```bash
20+
openclaw skills install green-api
21+
```
22+
23+
### 2. Connect the MCP server
24+
25+
Add to your OpenClaw config (`~/.openclaw/openclaw.json`):
26+
27+
```json
28+
{
29+
"mcpServers": {
30+
"green-api": {
31+
"url": "https://<your-host>/mcp"
32+
}
33+
}
34+
}
35+
```
36+
37+
If you deploy the server in hybrid mode, legacy SSE-only clients can use `https://<your-host>/sse` instead.
38+
39+
### 3. Authorize
40+
41+
On the first request, the MCP client will open a browser tab to `https://<your-host>/authorize`. Paste your **Instance ID** and **API Token** (from [console.green-api.com](https://console.green-api.com)) into the form. The bearer token issued by the OAuth flow is bound to those credentials for 24 hours — you won't be prompted again until it expires.
42+
43+
### 4. Start chatting
44+
45+
Once authorized, just describe what you want:
46+
47+
> "Send 'Hello!' to +7 987 654 3210 from instance 1234567"
48+
49+
## Links
50+
51+
- [GREEN-API Documentation](https://green-api.com/en/docs/)
52+
- [GREEN-API Console](https://console.green-api.com)

0 commit comments

Comments
 (0)