Cal.com MCP
oficialConecte 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 --openno 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.
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
- Node.js >= 18
- Uma chave de API do Cal.com — gere uma em Settings → Developer → API Keys
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
bookingseavailabilityestão habilitados, o que ocorre por padrão quando você não informatoolsets. 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, comobooking.created,booking.rescheduled,booking.cancelled,meeting.endederecording.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, edelivery.secretdeve ser um segredowhsec_. Antes de salvar a assinatura, o servidor envia uma solicitação de verificação assinada com um valorchallengeque 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
| Ferramenta | Descrição |
|---|---|
get_app_link | Cria 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
| Ferramenta | Descrição |
|---|---|
search_docs | Pesquisa a documentação do produto Cal.com; retorna páginas classificadas por relevância com um trecho do principal resultado |
Perfil do usuário
| Ferramenta | Descrição |
|---|---|
get_me | Obtém o perfil do usuário autenticado |
update_me | Atualiza seu perfil de usuário |
Tipos de evento
| Ferramenta | Descrição |
|---|---|
get_event_types | Lista todos os tipos de evento |
get_event_type | Obtém um tipo de evento específico pelo ID |
create_event_type | Cria um novo tipo de evento |
update_event_type | Atualiza um tipo de evento |
delete_event_type | Exclui um tipo de evento |
duplicate_event_type | Duplica um tipo de evento de equipe da organização na mesma equipe ou em outra equipe da organização |
get_event_type_settings | Obtém as configurações de um tipo de evento |
get_event_type_history | Obtém o histórico de alterações de um tipo de evento |
get_scheduling_config | Obtém a configuração de agendamento de um tipo de evento |
get_crm_sync_errors | Obté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.
| Ferramenta | Descrição |
|---|---|
get_events | Lista 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_event | Obtém um evento pelo uuid |
invite_cal_event_guests | Envia 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
| Ferramenta | Descrição |
|---|---|
get_bookings | Lista reservas com filtros opcionais |
get_booking | Obtém uma reserva específica pelo UID |
create_booking | Cria uma nova reserva |
reschedule_booking | Reagenda uma reserva |
cancel_booking | Cancela uma reserva |
confirm_booking | Confirma uma reserva pendente |
mark_booking_absent | Marca uma ausência em uma reserva |
get_booking_attendees | Obtém todos os participantes de uma reserva |
add_booking_attendee | Adiciona um participante a uma reserva |
get_booking_attendee | Obtém um participante específico |
get_booking_routing_trace | Obtém o rastreamento de roteamento de uma reserva |
get_org_team_bookings | Obtém as reservas de uma equipe da organização |
get_org_user_bookings | Obtém as reservas de um usuário da organização |
Agendas
| Ferramenta | Descrição |
|---|---|
get_schedules | Lista todas as agendas |
get_schedule | Obtém uma agenda específica pelo ID |
create_schedule | Cria uma nova agenda |
update_schedule | Atualiza uma agenda |
delete_schedule | Exclui uma agenda |
get_default_schedule | Obtém sua agenda padrão |
Disponibilidade e calendários
| Ferramenta | Descrição |
|---|---|
get_availability | Obtém horários disponíveis |
get_busy_times | Obtém horários ocupados dos calendários |
get_connected_calendars | Lista os calendários conectados |
get_conferencing_apps | Lista 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.
| Ferramenta | Descrição |
|---|---|
list_contacts | Lista 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_contact | Adiciona um contato pelo e-mail, com nome opcional |
update_contact | Atualiza o nome de um contato; não é possível alterar o nome de um contato que está no Cal |
remove_contact | Remove um contato e suas tags |
list_contact_tags | Lista suas tags, 50 por página, e informa quantos contatos têm cada uma |
create_contact_tag | Cria uma tag sem atribuí-la a nenhum contato |
add_contact_tag | Atribui uma tag a um contato |
remove_contact_tag | Remove 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.
| Ferramenta | Descrição |
|---|---|
search_listings | Pesquisar 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_listings | Ler 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_book | Fazer 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_online | Fazer 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_request | Solicitar 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
| Ferramenta | Descrição |
|---|---|
get_my_teams | Obter as equipes das quais você faz parte |
get_org_teams | Obter as equipes da organização |
create_team_invite | Convidar alguém para uma equipe |
create_team_membership | Criar uma associação a uma equipe |
get_team_memberships | Obter todas as associações a equipes |
get_team_membership | Obter uma associação a uma equipe |
update_team_membership | Atualizar uma associação a uma equipe |
delete_team_membership | Excluir uma associação a uma equipe |
Organizações
| Ferramenta | Descrição |
|---|---|
get_org_memberships | Obter todas as associações a organizações |
create_org_membership | Criar uma associação a uma organização |
get_org_membership | Obter uma associação a uma organização |
update_org_membership | Atualizar uma associação a uma organização |
delete_org_membership | Excluir uma associação a uma organização |
get_org_attributes | Obter os atributos da organização |
get_org_attribute | Obter um atributo da organização |
get_attribute_options | Obter as opções de um atributo |
get_user_attributes | Obter os atributos atribuídos a um usuário |
assign_attribute_to_user | Atribuir um atributo a um usuário |
update_user_attribute | Atualizar um atributo atribuído a um usuário |
unassign_attribute_from_user | Remover a atribuição de um atributo a um usuário |
get_user_attribute_history | Obter o histórico de atribuições de atributos de um usuário |
Formulários de roteamento
| Ferramenta | Descrição |
|---|---|
calculate_routing_form_slots | Calcular horários com base na resposta ao formulário de roteamento |
get_org_routing_forms | Obter os formulários de roteamento da organização |
get_org_routing_form_responses | Obter as respostas aos formulários de roteamento |
get_team_routing_forms | Obter os formulários de roteamento da equipe |
create_routing_form | Criar um formulário de roteamento da equipe que começa com uma rota alternativa |
get_routing_form | Obter as perguntas e rotas de um formulário de roteamento da equipe |
get_routing_form_history | Obter 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_routes | Visualizar e aplicar edições às rotas de um formulário de roteamento da equipe |
edit_routing_form_fields | Visualizar e aplicar edições às perguntas de um formulário de roteamento da equipe |
Catálogo da API
| Ferramenta | Descrição |
|---|---|
find_api_operation | Pesquisar o catálogo completo de operações da API v2 |
describe_api_operation | Obter o esquema de entrada de uma operação da API |
call_api_operation | Executar 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
- Guia de agentes de IA — crie agentes de IA usando diretamente a API do Cal.com
- Referência da API v2 — documentação completa dos endpoints da API
Esta documentação é criada e hospedada no Mintlify, uma plataforma de documentação para desenvolvedores.
