convez.ai
MCP ServerIntegração & APIsIntermediário
AdamNottea

Mahinatar MCP Server

AdamNottea/mahinatar-mcp

Automação de prospecção e outreach integrada ao seu MCP client

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que conecta Claude/Cursor ao Mahinatar, sua plataforma de automação de prospecção. Permite listar leads, gerar drafts personalizados de outreach e enviar emails de forma segura com validação em tempo real. Suporta autenticação por token JWT ou credenciais de email.

Instalação

$npx convez-ai AdamNottea/mahinatar-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Gerar e enviar campanhas de cold outreach personalizadas a partir de leads estruturados
  • Listar, filtrar e priorizar leads por status, email e website disponível
  • Acompanhar pipeline de vendas com resumos de contatos, follow-ups pendentes e receita
  • Automatizar busca de leads qualificados e ações recomendadas em uma só chamada

Veredito

MCP server robusto e bem pensado para equipes que usam Mahinatar. Modelo de segurança sólido (dry-run por padrão, RLS nativo) e interface clara via tools especializadas. Essencial se você já opera em Mahinatar; inútil fora desse ecossistema.

README

A tradução para o português deste README ainda está na fila.

mahinatar-mcp

An Elite-tier MCP server that connects Claude Code (or any MCP client) to a Mahinatar account and runs pipeline outreach — list leads, draft cold outreach offering a website, and send it (safely).

It authenticates as your own Mahinatar user against Mahinatar's Supabase backend using the public anon key, so every read and write runs under your Row Level Security — your data only. It never uses a service-role key.

Two ways to connect (pick one):

  1. Access token (recommended — required for Google-login users with no password). Set MAHINATAR_ACCESS_TOKEN to your own Supabase user JWT. See Token connect below.
  2. Email + password. Set MAHINATAR_EMAIL + MAHINATAR_PASSWORD. Only works if your account actually has a password.

Token auth is preferred whenever MAHINATAR_ACCESS_TOKEN is set.

Outreach is an Elite feature. Accounts on elite / admin / enterprise / agency plans (or an owner email) are authorized. Everyone else can call mahinatar_whoami, but the outreach tools refuse with an upgrade message.


Tools

ToolGateWhat it does
mahinatar_whoaminoneConnected email, user_id, plan, auth_method (token/password), authorized (Elite gate), live_send_enabled.
mahinatar_list_leadsEliteList leads. Args: status?, hasEmail?, limit? (default 25, max 100).
mahinatar_lead_detailEliteFull row for one lead. Args: id.
mahinatar_draft_outreachEliteStructured brief + a sendable first-draft email (no LLM call). Args: id, tone?, angle?. Always includes an opt-out line.
mahinatar_send_outreachEliteSend or dry-run an email. Args: id, subject, body, to?.
mahinatar_mark_contactedEliteMark a lead contacted + optional note. Args: id, note?. Thin wrapper over update_lead.
mahinatar_pipeline_summaryEliteSituational awareness: counts by status, total leads, #with email, #contacted, #sold, total revenue (if sale_amount exists). No args.
mahinatar_search_leadsEliteTargeted lead search. Args: query?, status?, hasEmail?, hasWebsite?, city?, limit? (default 25, max 100).
mahinatar_next_actionsElite"What should I do to make money right now." Ranked to-do list: high-value (no site + has email) → uncontacted-ready → stale follow-ups. Returns lead id, business, why-now. Args: limit? (default 15).
mahinatar_update_leadEliteGeneralized update: set status? and/or stage? (outreach_status) and/or append a timestamped note?. Defensive about columns. Args: id, status?, stage?, note?.
mahinatar_bulk_draft_outreachElitePersonalized drafts for many leads in one call (does not send). Args: ids? OR filter? (status,hasEmail,limit), tone?. Capped at 25.
mahinatar_due_followupsEliteLeads contacted > N days ago, not replied/closed. Args: days? (default 5).
mahinatar_list_sitesEliteYour generated websites (id, business, url, status) to reference when pitching. Args: status?, limit?.

Safety model (read this)

This server is built to make accidental mass-emailing impossible:

  • Dry-run by default. mahinatar_send_outreach returns { sent:false, dryRun:true, preview:{...} } and sends nothing unless live mode is fully configured.
  • Live send requires ALL of: MAHINATAR_OUTREACH_LIVE="true" and RESEND_API_KEY set and MAHINATAR_FROM_EMAIL set. Missing any one keeps you in dry-run.
  • Throttle: at most 20 live sends per server run (in-memory counter).
  • Suppression: leads flagged do_not_contact / unsubscribed are skipped (checked defensively — only if those columns exist).
  • Opt-out line is baked into every generated draft (CAN-SPAM friendly).
  • Never bulk-send without the live flag; the gate is enforced in src/email.ts (canSendLive()), the single source of truth.

For live send to actually deliver, you also need a warmed sending domain verified in Resend and a from address on that domain. Cold email to a fresh domain will land in spam — warm it first.


Setup

Requires Node 20+.

npm install
npm run build      # tsc → dist/

Configure via environment variables (see .env.example):

VarRequiredNotes
MAHINATAR_SUPABASE_URLyesDefaults to the EZUG project URL.
MAHINATAR_SUPABASE_ANON_KEYyesAnon/publishable key (never service-role).
MAHINATAR_ACCESS_TOKENone-ofRecommended. Your Supabase user JWT. Preferred when set.
MAHINATAR_REFRESH_TOKENnoOptional refresh token paired with the access token (lets the session refresh).
MAHINATAR_EMAILone-ofYour Mahinatar login email (password method).
MAHINATAR_PASSWORDone-ofYour Mahinatar password (password method).
RESEND_API_KEYnoRequired for live send only.
MAHINATAR_OUTREACH_LIVEno"true" to enable live send. Default dry-run.
MAHINATAR_FROM_EMAILnoVerified Resend sender. Live send only.

"one-of" = provide either MAHINATAR_ACCESS_TOKEN or MAHINATAR_EMAIL+MAHINATAR_PASSWORD.


Token connect

Google-login accounts have no password, so use your own Supabase session token instead. It's your session — the same credential your browser already holds — and it's scoped to your account by RLS exactly like password login.

  1. Log in to mahinatar.com in your browser.
  2. Open DevTools → Console and run:
    const k = Object.keys(localStorage).find(k => k.endsWith('-auth-token'));
    const s = JSON.parse(localStorage.getItem(k));
    console.log('ACCESS_TOKEN=', s.access_token);
    console.log('REFRESH_TOKEN=', s.refresh_token);
    
  3. Set MAHINATAR_ACCESS_TOKEN (and optionally MAHINATAR_REFRESH_TOKEN) in your MCP env.
  4. Run mahinatar_whoami — it should report your email, plan, and auth_method: "token".

Access tokens expire (typically ~1h). Providing the refresh token lets the session refresh itself; otherwise re-grab the access token when it expires.

How it works internally: the server attaches the token as Authorization: Bearer <token> on every Supabase request and calls auth.setSession() so getUser() resolves you — so RLS applies as your user and the Elite/plan gate works under either auth path. No service-role key, ever.


Add to Claude Code

Option A — claude mcp add

# Token method (recommended — works for Google-login users):
claude mcp add mahinatar -- node /Users/adamnottea/mahinatar-mcp/dist/index.js \
  -e MAHINATAR_SUPABASE_URL=https://ezugxjvjjqiccxocsojw.supabase.co \
  -e MAHINATAR_SUPABASE_ANON_KEY=your-anon-key \
  -e MAHINATAR_ACCESS_TOKEN=your-supabase-access-token \
  -e MAHINATAR_REFRESH_TOKEN=your-supabase-refresh-token

# Or password method:
#   -e MAHINATAR_EMAIL=you@example.com -e MAHINATAR_PASSWORD=your-password

(Add -e MAHINATAR_OUTREACH_LIVE=true -e RESEND_API_KEY=... -e MAHINATAR_FROM_EMAIL=... only when you're ready to send for real.)

Option B — .mcp.json / claude_desktop_config.json

{
  "mcpServers": {
    "mahinatar": {
      "command": "node",
      "args": ["/Users/adamnottea/mahinatar-mcp/dist/index.js"],
      "env": {
        "MAHINATAR_SUPABASE_URL": "https://ezugxjvjjqiccxocsojw.supabase.co",
        "MAHINATAR_SUPABASE_ANON_KEY": "your-anon-key",
        "MAHINATAR_EMAIL": "you@example.com",
        "MAHINATAR_PASSWORD": "your-password",
        "MAHINATAR_OUTREACH_LIVE": "false"
      }
    }
  }
}

Typical flow

  1. mahinatar_whoami → confirm authorized + auth_method, check live_send_enabled.
  2. mahinatar_pipeline_summary → situational awareness.
  3. mahinatar_next_actions → the ranked "what makes money right now" list.
  4. mahinatar_search_leads { hasEmail: true, status: "new", limit: 25 } (or mahinatar_due_followups { days: 5 } for follow-ups).
  5. mahinatar_bulk_draft_outreach { filter: { hasEmail: true, limit: 10 } } → personalize the drafts.
  6. mahinatar_send_outreach { id, subject, body } → dry-run preview first; enable live mode only when the copy and domain are ready.
  7. mahinatar_update_lead { id, status: "called", note: "..." } (or mahinatar_mark_contacted) to log the touch.
  8. mahinatar_list_sites → grab an already-built site URL to show in a pitch.

Development

npm run dev    # tsx, no build step

The server starts even with placeholder creds — auth happens on the first tool call and reports a clear error if credentials are wrong, rather than crashing.

Ver o original no GitHub

Bom para

Relacionados