@developer.k/ms-graph-mcp

Un servidor de protocolo de contexto de modelo (MCP) modular para Microsoft Graph y Microsoft 365.

Utiliza autenticación delegada mediante código de dispositivo y expone herramientas para Teams, correo de Outlook, Calendario, Microsoft To Do, Contactos, configuración del buzón y categorías de Outlook.

Repositorio de GitHub | Paquete npm

Consulta el registro de cambios para ver las notas de versión y los requisitos de actualización.

Características

Requisitos

• Node.js 18 o superior

• Un registro de aplicación de Microsoft Entra con flujos de cliente público habilitados

• Los permisos delegados de Microsoft Graph necesarios para los módulos que utilices

• Un buzón de Exchange Online o Outlook.com para Mail, Calendar, Contacts y la configuración del buzón

• Una licencia de Microsoft 365 u Office 365 que incluya Teams para las API de chat y canales de Teams

calendar_get_schedule y calendar_find_meeting_times están pensados para cuentas profesionales o educativas y no son compatibles con cuentas personales de Microsoft.

Para una cuenta personal de Outlook.com, registra una aplicación que admita cuentas personales de Microsoft y establece MS_TENANT_ID en common.

Sigue la Guía de configuración de la API de Microsoft Graph basada en capturas de pantalla para registrar una aplicación, añadir permisos y habilitar los flujos de cliente público.

Permisos delegados

El conjunto de ámbitos predeterminado solicita los permisos necesarios para cada módulo incluido:

Algunas políticas de inquilino requieren el consentimiento del administrador. Usa MS_GRAPH_SCOPES para solicitar un conjunto más reducido cuando solo se necesiten módulos seleccionados.

Inicio rápido

Configura tu cliente MCP para ejecutar el paquete publicado con npx. Los valores de configuración se pueden colocar directamente en el bloque env del cliente MCP; no se requieren variables de entorno del shell.

{
  "mcpServers": {
    "ms-graph": {
      "command": "npx",
      "args": ["-y", "@developer.k/ms-graph-mcp"],
      "env": {
        "MS_CLIENT_ID": "your-entra-application-client-id",
        "MS_TENANT_ID": "organizations"
      }
    }
  }
}

Llama a graph_auth_device_code, abre la URL de inicio de sesión devuelta, introduce el código de dispositivo y, a continuación, llama a graph_auth_status. Usa force: true después de añadir permisos o cuando un flujo de código de dispositivo antiguo haya caducado.

Configuración

Obligatorio:

• MS_CLIENT_ID: Identificador (cliente) de la aplicación de Microsoft Entra.

Opcional:

• MS_TENANT_ID: organizations, common o un identificador de directorio (inquilino). Valor predeterminado: organizations.

• MS_GRAPH_SCOPES: Ámbitos delegados separados por comas o espacios que sustituyen al conjunto de ámbitos predeterminado.

• MS_GRAPH_TOKEN_CACHE_PATH: Ruta local de la caché de tokens de MSAL.

• MS_GRAPH_ACCOUNT_USERNAME: Cuenta en caché que se debe seleccionar cuando hay más de una cuenta disponible.

Ejemplo de un conjunto de ámbitos personalizado centrado en la lectura:

{
  "env": {
    "MS_CLIENT_ID": "your-entra-application-client-id",
    "MS_TENANT_ID": "organizations",
    "MS_GRAPH_SCOPES": "User.Read Mail.Read Calendars.Read Tasks.Read Contacts.Read MailboxSettings.Read offline_access"
  }
}

Herramientas

Graph:

graph_auth_device_code
graph_auth_status
graph_get_me

Teams:

teams_list_joined_teams
teams_list_channels
teams_list_channel_messages
teams_send_channel_message
teams_list_chats
teams_list_chat_messages
teams_list_chat_members
teams_find_self_chat
teams_send_chat_message
teams_send_self_message

Mail:

mail_list_folders
mail_list_messages
mail_get_message
mail_list_attachments
mail_get_attachment
mail_add_attachment
mail_create_draft
mail_update_draft
mail_create_reply_draft
mail_create_forward_draft
mail_send_draft
mail_send_message
mail_reply
mail_reply_all
mail_forward
mail_update_message
mail_move_message
mail_delete_message
mail_list_rules
mail_create_rule
mail_update_rule
mail_delete_rule

Calendar:

calendar_list_calendars
calendar_get_calendar
calendar_create_calendar
calendar_update_calendar
calendar_delete_calendar
calendar_list_events
calendar_get_event
calendar_create_event
calendar_update_event
calendar_delete_event
calendar_cancel_event
calendar_respond_event
calendar_get_schedule
calendar_find_meeting_times

Microsoft To Do:

todo_list_task_lists
todo_get_task_list
todo_create_task_list
todo_update_task_list
todo_delete_task_list
todo_list_tasks
todo_get_task
todo_create_task
todo_update_task
todo_complete_task
todo_delete_task
todo_list_checklist_items
todo_create_checklist_item
todo_update_checklist_item
todo_delete_checklist_item
todo_list_linked_resources
todo_create_linked_resource
todo_delete_linked_resource

Contacts:

contacts_list_folders
contacts_get_folder
contacts_create_folder
contacts_update_folder
contacts_delete_folder
contacts_list
contacts_get
contacts_create
contacts_update
contacts_delete

Configuración y categorías de Outlook:

outlook_get_mailbox_settings
outlook_update_mailbox_settings
outlook_set_automatic_replies
outlook_list_categories
outlook_get_category
outlook_create_category
outlook_update_category
outlook_delete_category

Ejemplos de indicaciones

Show the 10 most recent unread messages in my Inbox.
Find messages containing "quarterly report" and summarize their subjects and senders.
Create a draft reply to this message, but do not send it.
Create a draft email to user@example.com with the subject "Project update".
Send draft MESSAGE_ID after showing me its current recipients and subject.
Move message MESSAGE_ID to folder FOLDER_ID.

Show my calendar events for next week in Asia/Seoul.
Find a 30-minute time when all three attendees are available.
Create a Teams online meeting tomorrow at 2 PM.
Accept event EVENT_ID and send a response.

List my Microsoft To Do task lists.
Add a high-priority task due Friday with a reminder one day earlier.
Add three checklist items to task TASK_ID.
Mark task TASK_ID as completed.

Find the contact with email user@example.com.
Create a business contact in folder FOLDER_ID.
Schedule automatic replies from Monday morning through Friday evening.
Create an Outlook category named "Customer" using preset7.

Prefiere las herramientas de borrador antes que las de envío de correo para que los destinatarios y el contenido puedan revisarse. Las herramientas de enviar, responder, reenviar, cancelar, mover y eliminar modifican datos reales de Microsoft 365.

Desarrollo local

Usa esta sección solo cuando ejecutes desde un clon local:

npm install
npm test

{
  "mcpServers": {
    "ms-graph": {
      "command": "node",
      "args": ["/path/to/ms-graph-mcp/build/index.js"],
      "env": {
        "MS_CLIENT_ID": "your-entra-application-client-id",
        "MS_TENANT_ID": "organizations"
      }
    }
  }
}

Estructura del proyecto

src/
|-- auth/
|   +-- msal.ts
|-- graph/
|   +-- client.ts
|-- modules/
|   |-- calendar.ts
|   |-- contacts.ts
|   |-- mail.ts
|   |-- outlook.ts
|   |-- shared.ts
|   |-- teams.ts
|   +-- todo.ts
|-- config.ts
|-- index.ts
|-- tools.ts
+-- types.ts

Limitaciones actuales

• Las herramientas operan sobre los recursos /me del usuario con la sesión iniciada. Los buzones compartidos y las carpetas compartidas delegadas aún no están expuestos.

• Las suscripciones a webhooks no están incluidas porque un servidor MCP stdio no tiene un punto de conexión de devolución de llamada público permanente.

• Los archivos adjuntos simples están limitados a 3 MiB. Los adjuntos más grandes requieren una sesión de carga de Microsoft Graph.

• El filtrado de contactos admite la coincidencia exacta de direcciones de correo electrónico. Microsoft Graph no expone la búsqueda general por nombre en la colección de contactos.

• Los cuerpos de eventos y mensajes pueden contener HTML externo proporcionado por Microsoft Graph.

Este paquete no contiene credenciales, identificadores de inquilino, identificadores de cuenta ni ninguna otra configuración personalizada.