HackMD

Un servidor del Protocolo de Contexto del Modelo para integrar la plataforma de toma de notas de HackMD con asistentes de IA.

GitHub
68

Documentación

Servidor MCP de HackMD

Un servidor de Model Context Protocol (MCP) que se integra con la API de HackMD, permitiendo que los clientes LLM accedan e interactúen con notas, equipos, perfiles de usuario y datos de historial de HackMD.

Características

  • Obtener información del perfil de usuario
  • Crear, leer, actualizar y eliminar notas
  • Gestionar notas de equipo y colaborar con miembros del equipo
  • Acceder al historial de lectura
  • Listar y gestionar equipos
  • Soporte de transporte dual: Transportes HTTP y STDIO
  • Listo para despliegue en la nube: Compatible con Smithery y otras plataformas

Requisitos

  • Node.js 18+

Instalación Local (Transporte STDIO)

  1. Añade este servidor a tu mcp.json / claude_desktop_config.json:
{
  "mcpServers": {
    "hackmd": {
      "command": "npx",
      "args": ["-y", "hackmd-mcp"],
      "env": {
        "HACKMD_API_TOKEN": "your_api_token"
      }
    }
  }
}

También puedes configurar opcionalmente la variable de entorno HACKMD_API_URL si necesitas usar un endpoint diferente de la API de HackMD.

  1. Reinicia tu cliente MCP (por ejemplo, Claude Desktop)
  2. Usa las herramientas para interactuar con HackMD

Despliegue del Servidor (Transporte HTTP)

Autoalojamiento

Sigue las instrucciones de Desarrollo Local para configurar el proyecto localmente y luego ejecuta:

pnpm run start:http

Esto iniciará el servidor en el puerto 8081 por defecto. Puedes cambiar el puerto configurando la variable de entorno PORT.

Despliegue en la Nube

Puedes desplegar este servidor MCP en cualquier plataforma en la nube que admita aplicaciones de servidor Node.js.

También puedes desplegarlo a través de plataformas MCP como Smithery.

Configuración

Variables de Entorno (Transporte STDIO y servidor de Transporte HTTP donde el host proporciona la configuración)

Cuando uses el transporte STDIO o alojes el servidor de transporte HTTP, puedes pasar la configuración mediante variables de entorno:

  • HACKMD_API_TOKEN: Token de la API de HackMD (Requerido para todas las operaciones)
  • HACKMD_API_URL: (Opcional) URL de la API de HackMD (Por defecto: https://api.hackmd.io/v1)

Variables de entorno aplicadas solo para el servidor de transporte HTTP:

  • ALLOWED_HACKMD_API_URLS: (Opcional) Lista separada por comas de URLs permitidas de la API de HackMD. El servidor rechazará las solicitudes si la URL de la API de HackMD proporcionada no está en esta lista. Si no se configura, solo se permite la URL predeterminada (https://api.hackmd.io/v1).

[!CAUTION] Si estás alojando el servidor de transporte HTTP con el token preconfigurado, debes proteger tu endpoint e implementar autenticación antes de permitir que los usuarios accedan a él. De lo contrario, cualquiera puede acceder a tu servidor MCP mientras usa tu token de HackMD.

Cabeceras HTTP (Transporte HTTP donde el usuario proporciona la configuración)

Cuando se usa el transporte HTTP, el usuario puede pasar la configuración mediante cabeceras HTTP:

  • Hackmd-Api-Token: Token de la API de HackMD (Requerido para todas las operaciones)
  • Hackmd-Api-Url: (Opcional) URL de la API de HackMD (Por defecto: https://api.hackmd.io/v1)

Si el usuario proporciona el token en la cabecera, mientras el servidor también tiene configurado HACKMD_API_TOKEN, el valor de la cabecera tendrá prioridad.

Obtener un Token de la API de HackMD

Para obtener un token de API, sigue estos pasos:

  1. Ve a Configuración de HackMD.
  2. Haz clic en "Create API Token".
  3. Copia el token generado y úsalo en tu archivo .env o en las variables de entorno.

Herramientas Disponibles

Herramientas de Perfil

  • get_user_info: Obtener información sobre el usuario autenticado

Herramientas de Equipos

  • list_teams: Listar todos los equipos accesibles para el usuario

Herramientas de Historial

  • get_history: Obtener el historial de lectura del usuario

Herramientas de Notas de Equipo

  • list_team_notes: Listar todas las notas de un equipo
  • create_team_note: Crear una nueva nota en un equipo
  • update_team_note: Actualizar una nota existente en un equipo
  • delete_team_note: Eliminar una nota de un equipo

Herramientas de Notas de Usuario

  • list_user_notes: Listar todas las notas propiedad del usuario
  • get_note: Obtener una nota por su ID
  • create_note: Crear una nueva nota
  • update_note: Actualizar una nota existente
  • delete_note: Eliminar una nota

Ejemplo de Uso

Gestión Básica de Notas

Can you help me manage my HackMD notes?

Listar Notas

Please list all my notes.

Crear una Nueva Nota

Create a new note with the title "Meeting Notes" and content:
```
# Meeting Notes

Discussion points:
- Item 1
- Item 2
```

Colaboración en Equipo

Show me all the teams I'm part of and list the notes in the first team.

Desarrollo Local

Este proyecto utiliza pnpm como gestor de paquetes.

Clona el repositorio e instala las dependencias:

git clone https://github.com/yuna0x0/hackmd-mcp.git
cd hackmd-mcp
pnpm install

Configuración

  1. Crea un archivo .env copiando el ejemplo:
cp env.example .env
  1. Edita el archivo .env y añade tu token de la API de HackMD:
HACKMD_API_TOKEN=your_api_token

Depuración con MCP Inspector

Puedes usar MCP Inspector para probar y depurar el servidor MCP de HackMD:

npx @modelcontextprotocol/inspector -e HACKMD_API_TOKEN=your_api_token npx hackmd-mcp

# Use this instead when Local Development
pnpm run inspector

Luego abre tu navegador en la URL proporcionada (normalmente http://localhost:6274) para acceder a la interfaz de MCP Inspector. Desde allí, puedes:

  1. Conectarte a tu servidor MCP de HackMD en ejecución
  2. Explorar las herramientas disponibles
  3. Ejecutar herramientas con parámetros personalizados
  4. Ver las respuestas

Esto es particularmente útil para probar tu configuración antes de conectarla a clientes MCP como Claude Desktop.

Docker

Extrae desde GitHub Container Registry:

docker pull ghcr.io/yuna0x0/hackmd-mcp

Compilación de Docker (Desarrollo Local):

docker build -t ghcr.io/yuna0x0/hackmd-mcp .

Compilación de Docker multi-plataforma (Desarrollo Local):

docker buildx build --platform linux/amd64,linux/arm64 -t ghcr.io/yuna0x0/hackmd-mcp .

MCP Bundles (MCPB)

Para crear un paquete MCP para este servidor, ejecuta:

pnpm run pack:mcpb

Aviso de Seguridad

Este servidor MCP acepta tu token de la API de HackMD en el archivo .env, variable de entorno o cabecera HTTP. Mantén esta información segura y nunca la envíes al control de versiones.

Licencia

Este proyecto está licenciado bajo la Licencia MIT: consulta el archivo LICENSE para más detalles.