Cal.com MCP

oficial

Conecte clientes de IA ao agendamento do Cal.com através do Model Context Protocol usando o servidor hospedado em mcp.cal.com ou uma instância local.

O que você pode fazer com Cal Com MCP?

  • Gerenciar agendamentos — Peça ao seu assistente para listar, criar, reagendar, cancelar ou confirmar agendamentos e adicionar participantes a eles.
  • Verificar disponibilidade — Consulte horários disponíveis, horários ocupados nos calendários conectados e sua agenda padrão.
  • Configurar tipos de evento — Crie, atualize, duplique ou exclua tipos de evento, incluindo tipos de evento de equipe.
  • Gerenciar agendas e contatos — Crie e edite agendas e adicione, atualize ou marque seus contatos pessoais.
  • Gerenciar equipes e organizações — Convide membros da equipe, gerencie associações e liste ou edite equipes e atributos da organização.
  • Pesquisar documentação e o catálogo da API — Pesquise a documentação do Cal.com ou encontre, descreva e chame qualquer operação da API v2.

Documentação

Servidor MCP

Conecte clientes de IA ao agendamento do Cal.com por meio do Model Context Protocol usando o servidor hospedado em mcp.cal.com ou uma instância local.

O servidor MCP do Cal.com envolve a API v2 do Cal.com no Model Context Protocol, permitindo gerenciar reservas, tipos de evento, agendas e muito mais usando linguagem natural em qualquer cliente compatível com MCP.

Servidor hospedado (mcp.cal.com)

A maneira mais rápida de começar é conectar seu cliente MCP diretamente a mcp.cal.com. O servidor hospedado usa o transporte Streamable HTTP com autenticação OAuth 2.1 — seu cliente gerencia o fluxo de autorização automaticamente.

Conecte seu cliente

Aponte seu cliente MCP para a URL do servidor hospedado:

https://mcp.cal.com/mcp

Na primeira conexão, seu cliente orienta você por um fluxo de autorização OAuth, no qual você concede ao servidor acesso à sua conta do Cal.com. Não é necessária uma chave de API. Qualquer cliente MCP pode se conectar: os clientes se registram dinamicamente por meio de POST /oauth/register ou se identificam com um Client ID Metadata Document (uma URL de client_id https). Antes de entrar no Cal.com, você verá uma página de consentimento que identifica o cliente e o host para o qual você será redirecionado.

[!NOTE]

A tela de consentimento também solicita escopos de equipe para criar, editar e excluir tipos de evento de equipe e para visualizar e gerenciar associações a equipes, permitindo que seu cliente de IA configure tipos de evento de equipe e adicione pessoas às equipes. Ela também solicita os escopos de perfil da organização, para que o cliente de IA de um administrador da organização possa listar, criar, editar e excluir as equipes da organização. O Cal.com continua verificando sua função e suas permissões na equipe em cada chamada. Também solicita permissão para visualizar, adicionar, renomear e remover seus contatos pessoais (CONTACT_READ, CONTACT_WRITE). Se você se conectou antes da inclusão desses escopos, desconecte e reconecte o servidor para concedê-los.

[tab] Claude Desktop

Adicione o seguinte ao seu claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "calcom": {
      "url": "https://mcp.cal.com/mcp"
    }
  }
}

[tab] Cursor

Abra Settings → MCP e adicione um novo servidor com a URL https://mcp.cal.com/mcp, ou adicione-a ao seu .cursor/mcp.json:

{
  "mcpServers": {
    "calcom": {
      "url": "https://mcp.cal.com/mcp"
    }
  }
}

[tab] VS Code

Adicione o servidor às configurações de MCP do VS Code:

{
  "mcpServers": {
    "calcom": {
      "url": "https://mcp.cal.com/mcp"
    }
  }
}

[tab] fx

Adicione o seguinte ao seu ~/.fx/mcp.json:

{
  "mcp": {
    "calcom": {
      "type": "http",
      "url": "https://mcp.cal.com/mcp"
    }
  }
}

Em seguida, execute /mcp auth calcom --open no fx para autorizar. Consulte a documentação de MCP do fx para saber mais sobre transportes, opções de autenticação e descoberta de ferramentas.

[tab] Grok

O Grok se conecta por meio do bot do Cal.com, em vez de uma configuração JSON. Em Settings → Developer → MCP, selecione Grok Bot em Client setup e, em seguida, escaneie o código QR ou clique em Add Bot para abrir o bot do Cal.com no Grok.

The MCP page in Cal.com developer settings with Grok Bot selected under Client setup, showing a QR code and an Add Bot button

Servidor auto-hospedado (stdio)

Se preferir executar o servidor localmente, você pode usar o transporte stdio com uma chave de API. Isso é útil para desenvolvimento ou quando você quer ter controle total sobre o servidor.

Pré-requisitos

Conecte seu cliente

Adicione o seguinte à configuração do seu cliente MCP:

{
  "mcpServers": {
    "calcom": {
      "command": "npx",
      "args": ["@calcom/cal-mcp@latest"],
      "env": {
        "CAL_API_KEY": "cal_live_xxxx"
      }
    }
  }
}

Substitua cal_live_xxxx pela sua chave de API.

[!WARNING]

Nunca compartilhe nem faça commit da sua chave de API. Se ela for exposta, revogue-a imediatamente nas configurações do Cal.com.

Conjuntos de ferramentas

Você pode restringir quais ferramentas o servidor registra para uma sessão adicionando um parâmetro de consulta toolsets à URL do servidor:

https://mcp.cal.com/mcp?toolsets=bookings,availability

Conjuntos de ferramentas válidos: profile, event-types, events, bookings, availability, schedules, calendars, contacts, discover, teams, organizations, routing-forms, catalog (as metatools find_api_operation / describe_api_operation / call_api_operation). Nomes desconhecidos são rejeitados com 400 invalid_request. Se o parâmetro for omitido, todas as ferramentas serão registradas; as ferramentas locais get_app_link e search_docs são sempre registradas, independentemente da seleção. Para um servidor stdio auto-hospedado, defina MCP_TOOLSETS.

Visualizações interativas (MCP Apps)

Em clientes compatíveis com MCP Apps, get_availability e get_bookings também exibem uma visualização interativa no chat, para que você possa escolher horários e gerenciar reservas clicando, em vez de digitar:

  • Seletor de horários (get_availability): horários disponíveis agrupados por dia. Use as setas para avançar ou voltar nas datas, clique em um horário, informe o nome e o e-mail do participante e clique em Book. Quando o assistente estiver encontrando um novo horário para uma reserva existente, clicar em um horário oferece a opção Move booking here.
  • Reservas (get_bookings): um cartão por reserva, com o horário e os participantes. As reservas futuras têm as opções Join (quando a reserva tem um link de reunião), Reschedule, que mostra os horários disponíveis da próxima semana para você escolher, e Cancel, que pede sua confirmação primeiro no cartão.

Os horários são exibidos no fuso horário informado pelo seu cliente, e as visualizações seguem o tema claro ou escuro dele. As ações são executadas pelas mesmas ferramentas create_booking, reschedule_booking e cancel_booking na sua conexão existente, e o assistente recebe informações sobre o que você fez.

[!NOTE]

As visualizações só ficam disponíveis quando os conjuntos de ferramentas bookings e availability estão habilitados, o que ocorre por padrão quando você não informa toolsets. Clientes sem suporte a MCP Apps recebem os mesmos resultados em texto de antes.

Assinaturas de eventos (MCP Events)

O servidor hospedado é compatível com MCP Events, permitindo que clientes com a versão de protocolo 2026-07-28 recebam notificações quando algo acontecer na sua conta do Cal.com, em vez de consultar repetidamente o servidor. O servidor anuncia o recurso events e processa três métodos:

  • events/list: retorna os eventos aos quais você pode se inscrever, como booking.created, booking.rescheduled, booking.cancelled, meeting.ended e recording.ready, cada um com um esquema de entrada e um esquema de payload.
  • events/subscribe: inscreve uma URL de callback em um evento. O callback deve ser uma URL HTTPS pública, e delivery.secret deve ser um segredo whsec_. Antes de salvar a assinatura, o servidor envia uma solicitação de verificação assinada com um valor challenge que seu endpoint deve devolver na resposta JSON. Se você se inscrever novamente com a mesma URL, evento e argumentos, a assinatura existente será renovada.
  • events/unsubscribe: remove uma das suas assinaturas. A chamada é bem-sucedida mesmo se a assinatura já não existir.

As entregas são assinadas com Standard Webhooks usando seu segredo whsec_. Por padrão, as assinaturas expiram após 7 dias; defina ttlMs para solicitar uma duração entre 1 hora e 30 dias.

Sua primeira assinatura cria um webhook do Cal.com na sua conta, que envia eventos para a rota POST /events/calcom/<ref> do servidor. A remoção da última assinatura exclui esse webhook. Você não chama essa rota diretamente.

[!NOTE]

MCP Events é disponibilizado somente pelo transporte Streamable HTTP, não pelo servidor stdio auto-hospedado. Não tem relação com o conjunto de ferramentas events, que gerencia páginas de RSVP do Cal Events.

Ferramentas disponíveis

O servidor MCP disponibiliza 85 ferramentas organizadas por categoria:

Links do app

FerramentaDescrição
get_app_linkCria uma URL que abre uma reserva, um tipo de evento, uma agenda, uma equipe, um formulário de roteamento ou uma página de configurações no app web do Cal.com

Documentação

FerramentaDescrição
search_docsPesquisa a documentação do produto Cal.com; retorna páginas classificadas por relevância com um trecho do principal resultado

Perfil do usuário

FerramentaDescrição
get_meObtém o perfil do usuário autenticado
update_meAtualiza seu perfil de usuário

Tipos de evento

FerramentaDescrição
get_event_typesLista todos os tipos de evento
get_event_typeObtém um tipo de evento específico pelo ID
create_event_typeCria um novo tipo de evento
update_event_typeAtualiza um tipo de evento
delete_event_typeExclui um tipo de evento
duplicate_event_typeDuplica um tipo de evento de equipe da organização na mesma equipe ou em outra equipe da organização
get_event_type_settingsObtém as configurações de um tipo de evento
get_event_type_historyObtém o histórico de alterações de um tipo de evento
get_scheduling_configObtém a configuração de agendamento de um tipo de evento
get_crm_sync_errorsObtém erros de sincronização com o CRM de um tipo de evento

Eventos

Cal Events são páginas de RSVP com data fixa, disponibilizadas em cal.com/{slug} — não são tipos de evento nem eventos de calendário. get_events e get_event precisam do escopo OAuth EVENT_READ, e invite_cal_event_guests precisa de EVENT_WRITE.

FerramentaDescrição
get_eventsLista os eventos que você possui ou coorganiza, do mais recente ao mais antigo; aceita paginação com limit (máximo de 250) e cursor, além do filtro slug
get_eventObtém um evento pelo uuid
invite_cal_event_guestsEnvia um convite por e-mail para cada endereço, para cada um dos seus contatos pelo ID (contactIds) ou para todos os contatos com uma das suas tags de contato (contactTagIds); os contatos precisam do recurso contacts; informa o resultado para cada endereço

Reservas

FerramentaDescrição
get_bookingsLista reservas com filtros opcionais
get_bookingObtém uma reserva específica pelo UID
create_bookingCria uma nova reserva
reschedule_bookingReagenda uma reserva
cancel_bookingCancela uma reserva
confirm_bookingConfirma uma reserva pendente
mark_booking_absentMarca uma ausência em uma reserva
get_booking_attendeesObtém todos os participantes de uma reserva
add_booking_attendeeAdiciona um participante a uma reserva
get_booking_attendeeObtém um participante específico
get_booking_routing_traceObtém o rastreamento de roteamento de uma reserva
get_org_team_bookingsObtém as reservas de uma equipe da organização
get_org_user_bookingsObtém as reservas de um usuário da organização

Agendas

FerramentaDescrição
get_schedulesLista todas as agendas
get_scheduleObtém uma agenda específica pelo ID
create_scheduleCria uma nova agenda
update_scheduleAtualiza uma agenda
delete_scheduleExclui uma agenda
get_default_scheduleObtém sua agenda padrão

Disponibilidade e calendários

FerramentaDescrição
get_availabilityObtém horários disponíveis
get_busy_timesObtém horários ocupados dos calendários
get_connected_calendarsLista os calendários conectados
get_conferencing_appsLista os aplicativos de videoconferência

Contatos

Seus contatos pessoais e as tags deles na página Contacts — nunca membros de equipes ou organizações. As listas precisam do escopo OAuth CONTACT_READ, e as operações de gravação precisam de CONTACT_WRITE. As tags são compartilhadas com seus links.

FerramentaDescrição
list_contactsLista seus contatos, 50 por página, opcionalmente apenas os que têm determinadas tags, e informa se cada um está no Cal e pode participar de uma reunião em grupo
add_contactAdiciona um contato pelo e-mail, com nome opcional
update_contactAtualiza o nome de um contato; não é possível alterar o nome de um contato que está no Cal
remove_contactRemove um contato e suas tags
list_contact_tagsLista suas tags, 50 por página, e informa quantos contatos têm cada uma
create_contact_tagCria uma tag sem atribuí-la a nenhum contato
add_contact_tagAtribui uma tag a um contato
remove_contact_tagRemove uma tag de um contato; a tag em si permanece

Descobrir

Listagens publicadas no Discover, pesquisadas ou lidas pelos IDs retornados por uma pesquisa, que exigem o escopo OAuth EVENT_TYPE_READ; ligações e reservas online em empresas encontradas na web e solicitações para ser avisado quando um prestador se cadastrar, que exigem PROFILE_WRITE.

FerramentaDescrição
search_listingsPesquisar listagens por categoria, texto livre, região, preço, duração e período com horários disponíveis, incluindo o link de reserva de cada listagem; quando não houver resultados na região, empresas encontradas na web nessa região
get_discover_listingsLer até 50 listagens conforme aparecem em seus cartões públicos, opcionalmente com o horário disponível mais próximo de cada uma nos próximos 7 dias
call_business_to_bookFazer com que Cal ligue para uma empresa que search_listings encontrou na web para reservar um serviço, após a aprovação do usuário; retorna a página da ligação para acompanhá-la
book_onlineFazer com que o agente de reservas do Cal reserve, por conta própria, um serviço na página de reservas de uma empresa que search_listings encontrou na web, após a aprovação do usuário; retorna a página da tarefa, onde o usuário escolhe uma opção e aprova o preço e os termos
record_service_requestSolicitar o envio de um e-mail para o endereço da sua conta quando um prestador de um serviço para o qual o Discover não tem uma listagem se cadastrar; fazer a mesma solicitação novamente para a mesma necessidade na mesma região dentro de 90 dias não altera nada

Equipes e associações

FerramentaDescrição
get_my_teamsObter as equipes das quais você faz parte
get_org_teamsObter as equipes da organização
create_team_inviteConvidar alguém para uma equipe
create_team_membershipCriar uma associação a uma equipe
get_team_membershipsObter todas as associações a equipes
get_team_membershipObter uma associação a uma equipe
update_team_membershipAtualizar uma associação a uma equipe
delete_team_membershipExcluir uma associação a uma equipe

Organizações

FerramentaDescrição
get_org_membershipsObter todas as associações a organizações
create_org_membershipCriar uma associação a uma organização
get_org_membershipObter uma associação a uma organização
update_org_membershipAtualizar uma associação a uma organização
delete_org_membershipExcluir uma associação a uma organização
get_org_attributesObter os atributos da organização
get_org_attributeObter um atributo da organização
get_attribute_optionsObter as opções de um atributo
get_user_attributesObter os atributos atribuídos a um usuário
assign_attribute_to_userAtribuir um atributo a um usuário
update_user_attributeAtualizar um atributo atribuído a um usuário
unassign_attribute_from_userRemover a atribuição de um atributo a um usuário
get_user_attribute_historyObter o histórico de atribuições de atributos de um usuário

Formulários de roteamento

FerramentaDescrição
calculate_routing_form_slotsCalcular horários com base na resposta ao formulário de roteamento
get_org_routing_formsObter os formulários de roteamento da organização
get_org_routing_form_responsesObter as respostas aos formulários de roteamento
get_team_routing_formsObter os formulários de roteamento da equipe
create_routing_formCriar um formulário de roteamento da equipe que começa com uma rota alternativa
get_routing_formObter as perguntas e rotas de um formulário de roteamento da equipe
get_routing_form_historyObter o histórico de alterações de um formulário de roteamento da equipe, da mais recente para a mais antiga: quem alterou o quê e quando; aceita limit (máx. 50) e paginação cursor
edit_routing_form_routesVisualizar e aplicar edições às rotas de um formulário de roteamento da equipe
edit_routing_form_fieldsVisualizar e aplicar edições às perguntas de um formulário de roteamento da equipe

Catálogo da API

FerramentaDescrição
find_api_operationPesquisar o catálogo completo de operações da API v2
describe_api_operationObter o esquema de entrada de uma operação da API
call_api_operationExecutar qualquer operação da API v2 do catálogo

Exemplos de prompts

Depois de conectar, você pode interagir com o Cal.com usando linguagem natural:

  • "Quais reservas tenho esta semana?"
  • "Crie um tipo de evento de 30 minutos chamado 'Quick Chat'"
  • "Cancele minha reunião com John amanhã"
  • "Mostre meus horários disponíveis para a próxima segunda-feira"
  • "Reagende minha reunião das 14h para quinta-feira às 15h"
  • "Quais tipos de evento tenho?"

Recursos relacionados

Esta documentação é criada e hospedada no Mintlify, uma plataforma de documentação para desenvolvedores.