bluesurf-mcp-node
It lets you explore BlueSurf projects/tickets and fetch ticket attachments, including downloading them locally.
List the user's projects, including id, smallCode, code, and name.
Find tickets assigned to the user in a project by smallCode, optionally including closed/final-state tickets.
Get details for a specific ticket by code such as
PROJ-123.List a ticket's Files-section attachments without downloading them.
Download one or all attachments from a ticket into a local destination folder, creating it if needed.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@bluesurf-mcp-node show me my assigned tickets in BlueSurf"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
bluesurf-mcp (Node.js)
Servidor MCP local para que Cursor u otros agentes lean tickets de BlueSurf,
adjunten un archivo, publiquen un comentario y registren tiempo en el daily report.
El CLI es login, logout, y sin argumentos el servidor por stdio.
El kanban se consulta con un POST de filtro. Las escrituras son
adjuntar_archivo, agregar_comentario y registrar_tiempo.
Hace falta Node.js 20 o superior.
Instalación
npm install -g bluesurf-mcp
bluesurf-mcp --helpRelated MCP server: ticket-triage-mcp
Desarrollo
Desde esta carpeta:
npm install
npm run build
npm test
node dist/bin.js --helpnpm test compila y corre la suite (sin red).npm publish compila antes de empaquetar.
Guardar credenciales (login / logout)
La contraseña no va en mcp.json. Una vez, en una terminal:
bluesurf-mcp loginSi no instalaste el paquete de forma global, el mismo login corre con npx:
npx -y bluesurf-mcp loginPide usuario y contraseña, valida contra BlueSurf y guarda la contraseña en el almacén del sistema (Credential Manager en Windows, Keychain en macOS, Secret Service en Linux). El username queda en un JSON local, sin la contraseña.
El servicio se llama bluesurf-mcp-node y el usuario vive en:
Windows:
%LOCALAPPDATA%\bluesurf-mcp-node\config.jsonmacOS / Linux:
~/.config/bluesurf-mcp-node/config.json(oXDG_CONFIG_HOME)
bluesurf-mcp logoutborra lo guardado.
Configuración (variables de entorno)
El entorno gana sobre lo guardado con login.
Claves canónicas BLUESURF_*; se aceptan SURF_* como fallback.
BLUESURF_BASE_URL— URL base (opcional; defaulthttps://surf.bluepeople.com).BLUESURF_COOKIE— cookie de sesión ya válida → usaCookieAuth.BLUESURF_USERNAME+BLUESURF_PASSWORD— credenciales → usaCredentialsAuth.
Precedencia: cookie en env → usuario/contraseña en env → bluesurf-mcp login.
El núcleo no persiste secretos. La cookie de sesión vive en memoria mientras corre el proceso.
Correr el servidor
bluesurf-mcpSe comunica por stdio. Sin argumentos no pide contraseña: usa el entorno o
las credenciales de login.
Registrar el MCP en Cursor
Con el paquete instalado de forma global:
{
"mcpServers": {
"bluesurf": {
"command": "bluesurf-mcp"
}
}
}npx descarga el paquete y ejecuta su binario:
{
"mcpServers": {
"bluesurf": {
"command": "npx",
"args": ["-y", "bluesurf-mcp"]
}
}
}-y evita la pregunta de confirmación de npx. Las variables BLUESURF_* en env siguen siendo válidas como override.
Esa configuración no pide la contraseña. Antes de usarla, guárdala una vez; Cursor reutiliza lo que quede en el almacén del sistema:
npx -y bluesurf-mcp loginTools expuestas
mis_proyectos— proyectos del usuario (id, smallCode, code, name).buscar_mis_tickets(project, include_closed=false)— tickets asignados al usuario.obtener_ticket(code)— detalle de un ticket por su código (p. ej.PROJ-123).listar_adjuntos(code)— archivos de la sección Files del ticket (id, name, is_image), sin descargarlos.descargar_adjuntos(code, destino, archivo_id)— guarda esos archivos endestino. Conarchivo_iddescarga solo uno; si no, todos. Devuelve id, name, path, content_type y size.adjuntar_archivo(code, ruta)— sube un archivo local a la sección Files. Devuelve id, name e is_image del archivo nuevo.agregar_comentario(code, texto)— publica un comentario. El texto se escapa y se envuelve en un párrafo HTML. Devuelve id, author, body y created_at.proyectos_reporte— proyectos activos para registrar tiempo (id, smallCode, code, name, categoryIds).listar_categorias(proyecto)— subcategorías del usuario. Conproyecto(smallCode) solo las de ese proyecto.mi_reporte_diario(fecha)— daily report de un día (YYYY-MM-DD).cerradoes true cuandostatuses 2.registrar_tiempo(fecha, lineas, confirmar)— agrega una o más líneas y reenvía el día en un solo guardado. Cada línea llevahoras,categoriay, si aplica,descripcion,proyecto,ticketypendiente. Sin ticket la descripción es obligatoria.confirmarcierra el día; por defecto guarda un borrador.
Usar el cliente desde Node
npm install bluesurf-mcpimport { BlueSurfClient, CredentialsAuth } from "bluesurf-mcp";El paquete es solo ESM. El consumidor entrega las credenciales o la cookie. El paquete no las guarda.
Available Tools
5 toolsbuscar_mis_ticketsBRead-only
Lista los tickets asignados al usuario en un proyecto de BlueSurf.
Inputs: project (required), include_closed.
descargar_adjuntosA
Descarga los adjuntos de un ticket a una carpeta local. Con archivo_id descarga solo uno; si no, todos.
Inputs: code (required), destino (required), archivo_id.
listar_adjuntosARead-only
Lista los archivos de la sección Files de un ticket, sin descargarlos.
Inputs: code (required).
mis_proyectosARead-only
Lista los proyectos del usuario (id, smallCode, code, name). El smallCode (p. ej. "PROJ") es lo que se pasa a buscar_mis_tickets.
Inputs: no named parameters.
obtener_ticketCRead-only
Devuelve el detalle de un ticket de BlueSurf por su código (p. ej. PROJ-123).
Inputs: code (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct role: listing projects, listing assigned tickets, retrieving ticket detail, listing attachments, and downloading attachments. The only adjacent pair, listar_adjuntos and descargar_adjuntos, is explicitly differentiated by listing vs downloading.
The names are consistently snake_case and mostly follow a Spanish verb_noun pattern. The minor deviation is mis_proyectos, which is a noun phrase rather than verb-led, and buscar_mis_tickets includes a possessive but remains understandable.
Five tools are well-scoped for a focused BlueSurf project/ticket/attachment workflow. Each tool earns its place without obvious redundancy.
The set covers the core read path: projects to assigned tickets to ticket detail to attachment listing/download. Minor gaps remain around broader ticket search/filtering and write operations such as creating or updating tickets, but the main browsing workflow is usable.
Maintenance
Related MCP Connectors
Read-only MCP access to sessions, funnels, campaigns, errors, live visitors, and anomalies.
Help desk for agents. Search questions and answers first. Read-only MCP.
Managed MCP gateway with OAuth, per-agent permissions, shared accounts and activity logs.
Read-only XH Agents MCP connector: service catalogue, payment info, verification checks.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables read-only MCP access to Tactical RMM, allowing agents to query devices, clients, sites, audit logs, software, and pending actions without any mutating capabilities.MIT
- AlicenseBqualityDmaintenanceEnables support agents to look up customer account details and billing or incident information through two read-only MCP tools for triage workflows.2MIT
- AlicenseNot gradedqualityDmaintenanceEnables read-only querying of Jira Server/Data Center projects, issues, comments, transitions, and issue types through MCP tools.708 npmMIT
- FlicenseNot gradedqualityCmaintenanceEnables read-only retrieval of Jira Cloud issues, JQL search, and project issue listing through MCP tools.-