mcp-bitrix24 0.1.0__py3-none-any.whl

mcp_bitrix24/client.py

@@ -0,0 +1,130 @@
+import httpx
+import os
+from datetime import date, timedelta
+from typing import Any
+
+
+class BitrixClient:
+    def __init__(self, webhook_url: str | None = None):
+        self.webhook_url = (webhook_url or os.getenv("BITRIX24_WEBHOOK_URL", "")).rstrip("/")
+        if not self.webhook_url:
+            raise ValueError("BITRIX24_WEBHOOK_URL não configurado")
+
+    def _call(self, method: str, params: dict[str, Any] | None = None) -> Any:
+        url = f"{self.webhook_url}/{method}"
+        response = httpx.post(url, json=params or {}, timeout=30)
+        response.raise_for_status()
+        data = response.json()
+        if "error" in data:
+            raise RuntimeError(f"Bitrix24 error: {data.get('error_description', data['error'])}")
+        return data.get("result")
+
+    def list_deals(
+        self,
+        filter: dict | None = None,
+        select: list[str] | None = None,
+        order: dict | None = None,
+        start: int = 0,
+    ) -> list[dict]:
+        params: dict[str, Any] = {"start": start}
+        if filter:
+            params["filter"] = filter
+        if select:
+            params["select"] = select
+        if order:
+            params["order"] = order
+        result = self._call("crm.deal.list", params)
+        return result if isinstance(result, list) else []
+
+    def get_deal(self, deal_id: int) -> dict:
+        return self._call("crm.deal.get", {"id": deal_id})
+
+    def create_deal(self, fields: dict) -> int:
+        return self._call("crm.deal.add", {"fields": fields})
+
+    def update_deal(self, deal_id: int, fields: dict) -> bool:
+        return self._call("crm.deal.update", {"id": deal_id, "fields": fields})
+
+    def get_stages(self, pipeline_id: int | None = None) -> list[dict]:
+        params: dict[str, Any] = {}
+        if pipeline_id is not None:
+            params["filter"] = {"CATEGORY_ID": pipeline_id}
+        return self._call("crm.dealcategory.stage.list", params) or []
+
+    def add_comment(self, deal_id: int, comment: str) -> int:
+        fields = {
+            "OWNER_TYPE_ID": 2,
+            "OWNER_ID": deal_id,
+            "TYPE_ID": 12,
+            "SUBJECT": "Nota",
+            "DESCRIPTION": comment,
+            "DESCRIPTION_TYPE": 1,
+            "COMPLETED": "Y",
+            "DIRECTION": 0,
+        }
+        return self._call("crm.activity.add", {"fields": fields})
+
+    def add_task(self, deal_id: int, subject: str, description: str = "", deadline: str = "") -> int:
+        fields: dict[str, Any] = {
+            "OWNER_TYPE_ID": 2,
+            "OWNER_ID": deal_id,
+            "TYPE_ID": 6,
+            "SUBJECT": subject,
+            "DESCRIPTION": description,
+            "COMPLETED": "N",
+            "DIRECTION": 0,
+        }
+        if deadline:
+            fields["DEADLINE"] = deadline
+        return self._call("crm.activity.add", {"fields": fields})
+
+    def list_pipelines(self) -> list[dict]:
+        return self._call("crm.dealcategory.list") or []
+
+    def list_tasks(
+        self,
+        responsible_id: int | None = None,
+        overdue_only: bool = False,
+        due_today: bool = False,
+        due_this_week: bool = False,
+        start: int = 0,
+    ) -> list[dict]:
+        filter: dict[str, Any] = {"!STATUS": 5}
+        if responsible_id:
+            filter["RESPONSIBLE_ID"] = responsible_id
+        if overdue_only:
+            filter["<=DEADLINE"] = date.today().isoformat()
+        if due_today:
+            filter[">=DEADLINE"] = date.today().isoformat()
+            filter["<=DEADLINE"] = date.today().isoformat()
+        if due_this_week:
+            filter[">=DEADLINE"] = date.today().isoformat()
+            filter["<=DEADLINE"] = (date.today() + timedelta(days=7)).isoformat()
+
+        params: dict[str, Any] = {
+            "filter": filter,
+            "select": ["ID", "TITLE", "DEADLINE", "RESPONSIBLE_ID", "STATUS", "UF_CRM_TASK"],
+            "order": {"ID": "desc"},
+            "start": start,
+        }
+        result = self._call("tasks.task.list", params)
+        if isinstance(result, dict):
+            return result.get("tasks", [])
+        return []
+
+    def list_dormant_deals(self, days: int = 20) -> list[dict]:
+        cutoff = (date.today() - timedelta(days=days)).isoformat()
+        return self.list_deals(
+            filter={"<=DATE_MODIFY": cutoff, "CLOSED": "N"},
+            select=["ID", "TITLE", "STAGE_ID", "DATE_MODIFY", "ASSIGNED_BY_ID", "OPPORTUNITY", "CURRENCY_ID"],
+            order={"DATE_MODIFY": "ASC"},
+        )
+
+    def list_closing_this_week(self) -> list[dict]:
+        today = date.today().isoformat()
+        next_week = (date.today() + timedelta(days=7)).isoformat()
+        return self.list_deals(
+            filter={">=CLOSEDATE": today, "<=CLOSEDATE": next_week, "CLOSED": "N"},
+            select=["ID", "TITLE", "STAGE_ID", "CLOSEDATE", "OPPORTUNITY", "CURRENCY_ID", "ASSIGNED_BY_ID"],
+            order={"CLOSEDATE": "ASC"},
+        )

mcp_bitrix24/server.py

@@ -0,0 +1,259 @@
+import json
+import os
+from dotenv import load_dotenv
+from mcp.server.fastmcp import FastMCP
+from mcp_bitrix24.client import BitrixClient
+
+load_dotenv()
+
+mcp = FastMCP("Bitrix24 CRM")
+client = BitrixClient()
+
+
+@mcp.tool()
+def list_deals(
+    stage: str = "",
+    responsible_id: int = 0,
+    title_contains: str = "",
+    limit: int = 20,
+) -> str:
+    """Lista deals do Bitrix24. Filtre por estágio, responsável ou texto no título."""
+    filter: dict = {}
+    if stage:
+        filter["STAGE_ID"] = stage
+    if responsible_id:
+        filter["ASSIGNED_BY_ID"] = responsible_id
+    if title_contains:
+        filter["%TITLE"] = title_contains
+
+    select = ["ID", "TITLE", "STAGE_ID", "OPPORTUNITY", "CURRENCY_ID",
+              "ASSIGNED_BY_ID", "DATE_CREATE", "CLOSEDATE", "COMMENTS"]
+
+    deals = client.list_deals(filter=filter or None, select=select)
+    deals = deals[:limit]
+
+    if not deals:
+        return "Nenhum deal encontrado com os filtros fornecidos."
+
+    lines = [f"Encontrados {len(deals)} deals:\n"]
+    for d in deals:
+        valor = f"{d.get('OPPORTUNITY', '0')} {d.get('CURRENCY_ID', '')}"
+        lines.append(
+            f"• [{d['ID']}] {d['TITLE']}\n"
+            f"  Estágio: {d.get('STAGE_ID')} | Valor: {valor}\n"
+            f"  Responsável ID: {d.get('ASSIGNED_BY_ID')} | Fechamento: {d.get('CLOSEDATE', 'N/A')}"
+        )
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def get_deal(deal_id: int) -> str:
+    """Retorna todos os detalhes de um deal específico pelo ID."""
+    deal = client.get_deal(deal_id)
+    if not deal:
+        return f"Deal {deal_id} não encontrado."
+    return json.dumps(deal, ensure_ascii=False, indent=2)
+
+
+@mcp.tool()
+def create_deal(
+    title: str,
+    stage_id: str = "",
+    value: float = 0.0,
+    currency: str = "BRL",
+    contact_id: int = 0,
+    company_id: int = 0,
+    responsible_id: int = 0,
+    comments: str = "",
+    close_date: str = "",
+) -> str:
+    """
+    Cria um novo deal no Bitrix24.
+    close_date deve estar no formato YYYY-MM-DD.
+    """
+    fields: dict = {"TITLE": title, "CURRENCY_ID": currency}
+    if stage_id:
+        fields["STAGE_ID"] = stage_id
+    if value:
+        fields["OPPORTUNITY"] = value
+    if contact_id:
+        fields["CONTACT_ID"] = contact_id
+    if company_id:
+        fields["COMPANY_ID"] = company_id
+    if responsible_id:
+        fields["ASSIGNED_BY_ID"] = responsible_id
+    if comments:
+        fields["COMMENTS"] = comments
+    if close_date:
+        fields["CLOSEDATE"] = f"{close_date}T00:00:00+03:00"
+
+    new_id = client.create_deal(fields)
+    return f"Deal criado com sucesso! ID: {new_id}"
+
+
+@mcp.tool()
+def update_deal(deal_id: int, fields_json: str) -> str:
+    """
+    Atualiza campos de um deal existente.
+    fields_json deve ser um JSON com os campos a atualizar.
+    Exemplo: {"TITLE": "Novo nome", "OPPORTUNITY": 5000}
+    """
+    try:
+        fields = json.loads(fields_json)
+    except json.JSONDecodeError as e:
+        return f"Erro: fields_json inválido — {e}"
+
+    client.update_deal(deal_id, fields)
+    return f"Deal {deal_id} atualizado com sucesso."
+
+
+@mcp.tool()
+def move_deal_stage(deal_id: int, stage_id: str) -> str:
+    """
+    Move um deal para um estágio do funil.
+    Use list_stages para ver os estágios disponíveis.
+    """
+    client.update_deal(deal_id, {"STAGE_ID": stage_id})
+    return f"Deal {deal_id} movido para o estágio '{stage_id}'."
+
+
+@mcp.tool()
+def list_stages(pipeline_id: int = 0) -> str:
+    """Lista os estágios disponíveis no funil. pipeline_id=0 lista o funil padrão."""
+    stages = client.get_stages(pipeline_id if pipeline_id else None)
+    if not stages:
+        return "Nenhum estágio encontrado."
+    lines = ["Estágios disponíveis:"]
+    for s in stages:
+        lines.append(f"• {s.get('STATUS_ID')} — {s.get('NAME')}")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def add_comment(deal_id: int, comment: str) -> str:
+    """Adiciona uma nota/comentário a um deal."""
+    activity_id = client.add_comment(deal_id, comment)
+    return f"Comentário adicionado ao deal {deal_id}. Atividade ID: {activity_id}"
+
+
+@mcp.tool()
+def add_task(deal_id: int, subject: str, description: str = "", deadline: str = "") -> str:
+    """
+    Adiciona uma tarefa a um deal.
+    deadline deve estar no formato YYYY-MM-DDTHH:MM:SS+HH:MM.
+    """
+    activity_id = client.add_task(deal_id, subject, description, deadline)
+    return f"Tarefa '{subject}' adicionada ao deal {deal_id}. Atividade ID: {activity_id}"
+
+
+@mcp.tool()
+def list_pipelines() -> str:
+    """Lista todos os funis (pipelines) de deals disponíveis."""
+    pipelines = client.list_pipelines()
+    if not pipelines:
+        return "Apenas o funil padrão (ID: 0) está disponível."
+    lines = ["Funis disponíveis:"]
+    for p in pipelines:
+        lines.append(f"• ID: {p.get('ID')} — {p.get('NAME')}")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def list_tasks(
+    responsible_id: int = 0,
+    overdue_only: bool = False,
+    due_this_week: bool = False,
+    limit: int = 20,
+) -> str:
+    """Lista tarefas pendentes do Bitrix24. overdue_only=true retorna só as atrasadas. due_this_week=true retorna tarefas com prazo nos próximos 7 dias."""
+    tasks = client.list_tasks(
+        responsible_id=responsible_id or None,
+        overdue_only=overdue_only,
+        due_this_week=due_this_week,
+    )
+    tasks = tasks[:limit]
+
+    if not tasks:
+        return "Nenhuma tarefa encontrada."
+
+    lines = [f"Encontradas {len(tasks)} tarefas:\n"]
+    for t in tasks:
+        deadline = t.get("deadline") or t.get("DEADLINE") or "sem prazo"
+        crm_link = t.get("ufCrmTask") or t.get("UF_CRM_TASK") or ""
+        lines.append(
+            f"• [{t.get('id') or t.get('ID')}] {t.get('title') or t.get('TITLE')}\n"
+            f"  Prazo: {deadline} | Status: {t.get('status') or t.get('STATUS')}\n"
+            f"  Responsável ID: {t.get('responsibleId') or t.get('RESPONSIBLE_ID')} | CRM: {crm_link}"
+        )
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def daily_briefing(dormant_days: int = 20) -> str:
+    """
+    Gera um briefing consolidado do dia: tarefas atrasadas, tarefas para hoje,
+    deals dormentes e deals com fechamento previsto para esta semana.
+    dormant_days: quantos dias sem atividade para considerar um deal dormente (padrão: 20).
+    """
+    from datetime import date
+    today = date.today().strftime("%d/%m/%Y")
+    sections = [f"BRIEFING DO DIA — {today}\n"]
+
+    # Tarefas atrasadas
+    overdue = client.list_tasks(overdue_only=True)
+    if overdue:
+        sections.append(f"TAREFAS ATRASADAS ({len(overdue)})")
+        for t in overdue[:10]:
+            deal = (t.get("ufCrmTask") or [""])[0]
+            deadline = (t.get("deadline") or "sem prazo")[:10]
+            sections.append(f"  • [{t.get('id')}] {t.get('title')} | prazo: {deadline} | deal: {deal}")
+    else:
+        sections.append("TAREFAS ATRASADAS\n  Nenhuma.")
+
+    sections.append("")
+
+    # Tarefas para hoje
+    today_tasks = client.list_tasks(due_today=True)
+    if today_tasks:
+        sections.append(f"TAREFAS PARA HOJE ({len(today_tasks)})")
+        for t in today_tasks[:10]:
+            deal = (t.get("ufCrmTask") or [""])[0]
+            sections.append(f"  • [{t.get('id')}] {t.get('title')} | deal: {deal}")
+    else:
+        sections.append("TAREFAS PARA HOJE\n  Nenhuma.")
+
+    sections.append("")
+
+    # Deals dormentes
+    dormant = client.list_dormant_deals(days=dormant_days)
+    if dormant:
+        sections.append(f"DEALS DORMENTES — sem atividade há +{dormant_days} dias ({len(dormant)})")
+        for d in dormant[:10]:
+            modified = (d.get("DATE_MODIFY") or "")[:10]
+            valor = f"{d.get('OPPORTUNITY', '0')} {d.get('CURRENCY_ID', '')}"
+            sections.append(f"  • [{d['ID']}] {d['TITLE']} | estágio: {d.get('STAGE_ID')} | último update: {modified} | valor: {valor}")
+    else:
+        sections.append(f"DEALS DORMENTES\n  Nenhum deal parado há mais de {dormant_days} dias.")
+
+    sections.append("")
+
+    # Forecast da semana
+    closing = client.list_closing_this_week()
+    if closing:
+        sections.append(f"FECHAMENTO PREVISTO ESTA SEMANA ({len(closing)})")
+        for d in closing[:10]:
+            closedate = (d.get("CLOSEDATE") or "")[:10]
+            valor = f"{d.get('OPPORTUNITY', '0')} {d.get('CURRENCY_ID', '')}"
+            sections.append(f"  • [{d['ID']}] {d['TITLE']} | fechamento: {closedate} | valor: {valor}")
+    else:
+        sections.append("FECHAMENTO PREVISTO ESTA SEMANA\n  Nenhum deal.")
+
+    return "\n".join(sections)
+
+
+def main():
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

mcp_bitrix24-0.1.0.dist-info/METADATA

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: mcp-bitrix24
+Version: 0.1.0
+Summary: MCP Server for Bitrix24 CRM — manage deals via Claude
+Project-URL: Homepage, https://github.com/lucbrito88-boop/mcp-bitrix24
+Project-URL: Repository, https://github.com/lucbrito88-boop/mcp-bitrix24
+License: MIT
+Keywords: ai,bitrix24,claude,crm,mcp
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Description-Content-Type: text/markdown
+
+# Bitrix24 MCP Server
+
+MCP Server que integra o CRM Bitrix24 ao Claude, permitindo gerenciar deals diretamente via linguagem natural.
+
+## O que você pode fazer
+
+Após configurar, você pode pedir ao Claude coisas como:
+
+- *"Liste meus deals em aberto"*
+- *"Mostre os detalhes do deal 123"*
+- *"Crie um deal chamado 'Proposta NTSec' no valor de R$ 50.000"*
+- *"Mova o deal 456 para a etapa de negociação"*
+- *"Adicione uma nota no deal 789: reunião realizada com sucesso"*
+- *"Quais são os estágios do meu funil?"*
+- *"Liste minhas tarefas atrasadas"*
+- *"Quais tarefas estão pendentes para o responsável 42?"*
+
+## Ferramentas disponíveis
+
+| Ferramenta | Descrição |
+|---|---|
+| `list_deals` | Lista deals com filtros por estágio, responsável ou título |
+| `get_deal` | Retorna todos os detalhes de um deal pelo ID |
+| `create_deal` | Cria um novo deal no CRM |
+| `update_deal` | Atualiza campos de um deal existente |
+| `move_deal_stage` | Move um deal para outro estágio do funil |
+| `list_stages` | Lista os estágios disponíveis no funil |
+| `add_comment` | Adiciona nota/comentário a um deal |
+| `add_task` | Cria uma tarefa vinculada a um deal |
+| `list_tasks` | Lista tarefas pendentes; filtra por responsável ou só atrasadas |
+| `list_pipelines` | Lista os funis de deals disponíveis |
+
+## Pré-requisitos
+
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/) (gerenciador de pacotes)
+- Claude Code CLI
+- Conta no Bitrix24 com acesso à API (webhook configurado)
+
+## Instalação
+
+### 1. Clone o repositório
+
+```bash
+git clone https://github.com/seu-usuario/bitrix24-mcp.git
+cd bitrix24-mcp
+```
+
+### 2. Crie o ambiente virtual e instale as dependências
+
+```bash
+uv venv .venv
+uv pip install -r requirements.txt
+```
+
+### 3. Configure o webhook do Bitrix24
+
+Copie o arquivo de exemplo e adicione sua URL:
+
+```bash
+cp .env.example .env
+```
+
+Edite o `.env`:
+
+```env
+BITRIX24_WEBHOOK_URL=https://seudominio.bitrix24.com.br/rest/USER_ID/WEBHOOK_TOKEN/
+```
+
+**Como obter o webhook no Bitrix24:**
+1. Acesse seu Bitrix24 → Configurações → Integrações → Webhooks de entrada
+2. Crie um webhook com permissões de CRM (leitura e escrita)
+3. Copie a URL gerada
+
+### 4. Configure o MCP Server no Claude Code
+
+Adicione ao seu `.claude/settings.json` (ou `~/.claude/settings.json` para uso global):
+
+```json
+{
+  "mcpServers": {
+    "bitrix24": {
+      "command": "/caminho/para/bitrix24-mcp/.venv/Scripts/python.exe",
+      "args": ["/caminho/para/bitrix24-mcp/server.py"]
+    }
+  }
+}
+```
+
+> **Windows:** use `.venv\Scripts\python.exe`  
+> **Mac/Linux:** use `.venv/bin/python`
+
+### 5. Reinicie o Claude Code
+
+Feche e reabra o Claude Code. O MCP server `bitrix24` deve aparecer disponível.
+
+## Estrutura do projeto
+
+```
+bitrix24-mcp/
+├── src/mcp_bitrix24/
+│   ├── server.py        # MCP server — define as ferramentas expostas ao Claude
+│   └── client.py        # Wrapper da API REST do Bitrix24
+├── pyproject.toml       # Configuração do pacote (PyPI)
+├── requirements.txt     # Dependências Python
+├── .env.example         # Template de configuração
+└── .gitignore
+```
+
+## Dependências
+
+- [`mcp`](https://github.com/anthropics/mcp) — SDK do Model Context Protocol
+- [`httpx`](https://www.python-httpx.org/) — cliente HTTP assíncrono
+- [`python-dotenv`](https://github.com/theskumar/python-dotenv) — carregamento do `.env`
+
+## Segurança
+
+- O arquivo `.env` está no `.gitignore` — nunca commite suas credenciais
+- O webhook do Bitrix24 deve ter permissões de CRM e Tarefas (task)
+- Recomenda-se criar um usuário de serviço dedicado no Bitrix24 para o webhook

mcp_bitrix24-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+mcp_bitrix24/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcp_bitrix24/client.py,sha256=VJnYNDM2SOOS8wzwCW-bOVytz7BRSYejYB5uzvLsol0,4909
+mcp_bitrix24/server.py,sha256=fPFP411ieQF_h7lHR9977hdNniCL-Z66X4fZKBScPRM,8651
+mcp_bitrix24-0.1.0.dist-info/METADATA,sha256=P1R8iBaypVtTMkYR6ls76JwyPzfLHBmNZhpPj4aZBvw,4124
+mcp_bitrix24-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+mcp_bitrix24-0.1.0.dist-info/entry_points.txt,sha256=MyLb0Z8DmN_V00LsrmrA6l8IZ7LIHGzgkACS_RLn1PY,58
+mcp_bitrix24-0.1.0.dist-info/RECORD,,

mcp_bitrix24-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

mcp_bitrix24-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-bitrix24 = mcp_bitrix24.server:main