Atlassian Read-only MCP

Un pequeño servidor MCP que ofrece a los asistentes de IA acceso de solo lectura a Jira y Confluence Cloud. El acceso de solo lectura se aplica en dos capas:

1. Los tokens de Atlassian contienen únicamente permisos de lectura.

2. El servidor solo implementa solicitudes GET de la lista permitida.

Expone cuatro herramientas:

• Leer una incidencia de Jira

• Buscar en Jira con JQL

• Leer una página de Confluence

• Buscar en Confluence con CQL

No hay una herramienta HTTP genérica ni implementación de POST, PUT, PATCH o DELETE. Aunque se proporcionaran por accidente credenciales con más permisos, los clientes MCP seguirían sin tener ninguna herramienta para modificar contenido de Jira o Confluence. Las respuestas están limitadas, los posibles secretos se ocultan, el HTML de almacenamiento de Confluence se convierte a Markdown y las proyecciones JMESPath opcionales pueden reducir los datos devueltos.

Requisitos

• Node.js 20 o superior

• Acceso al tenant de Atlassian Cloud configurado

• Tokens de API con permisos separados para Jira y Confluence

• Un cliente MCP como GitHub Copilot en VS Code

Related MCP server: MCP Atlassian Server

Instalación

git clone https://github.com/AlexSchaap-TMMC/atlassian-readonly-mcp.git C:\Tools\atlassian-readonly
Set-Location C:\Tools\atlassian-readonly
npm install
npm test

Crear tokens de API

Abre la página Atlassian API tokens y crea dos tokens.

Token de Jira

read:jira-work

Este permiso clásico por sí solo está verificado para la recuperación de incidencias y la búsqueda con JQL. Atlassian rechazó los tokens de Jira que contenían solo los permisos granulares equivalentes con 401 Unauthorized; scope does not match.

Token de Confluence

read:page:confluence
read:content-details:confluence
search:confluence

Estos permisos granulares están verificados para la búsqueda CQL y la recuperación de páginas completas.

Los permisos se fijan cuando se crea un token. Jira y Confluence requieren tokens separados. Copia cada token desde el diálogo de creación de un solo uso y no lo pongas en archivos de código, configuración de MCP, historial del shell, incidencias ni chats.

No añadas permisos de escritura ni de administración. Los tokens restringidos garantizan que Atlassian rechace las operaciones de escritura de forma independiente de la implementación del servidor MCP.

Guardar credenciales

Desde el directorio del repositorio:

npm run configure -- jira
npm run configure -- confluence

El sistema de entrada oculta guarda cada token por separado en el Administrador de credenciales de Windows, el Llavero de macOS o el Servicio de secretos de Linux. El correo electrónico de la cuenta de Atlassian pertenece al entorno de MCP, no al almacén de credenciales.

Configurar GitHub Copilot en VS Code

Ejecuta MCP: Open User Configuration desde la paleta de comandos:

{
  "servers": {
    "atlassian-readonly": {
      "type": "stdio",
      "command": "node",
      "args": ["C:\\Tools\\atlassian-readonly\\src\\server.mjs"],
      "env": {
        "ATLASSIAN_USER_EMAIL": "your.atlassian.email@example.com",
        "NODE_OPTIONS": "--use-system-ca"
      }
    }
  }
}

Recarga VS Code, abre Copilot Chat, selecciona Configure Tools y habilita las cuatro herramientas de Atlassian.

Ejemplos de prompts:

Read HEC-123 and summarize its acceptance criteria.
Search Jira for open bugs assigned to me.
Search Confluence for pages about Kafka retry handling.

Configurar la CLI de GitHub Copilot

copilot mcp add atlassian-readonly `
  --env ATLASSIAN_USER_EMAIL="your.atlassian.email@example.com" `
  --env NODE_OPTIONS="--use-system-ca" `
  -- node C:\Tools\atlassian-readonly\src\server.mjs

Reinicia la CLI de Copilot después de añadir o cambiar el servidor.

Solución de problemas

Autenticación

Comprueba que:

• El correo electrónico coincide con la cuenta de Atlassian que creó los tokens.

• Se guardó el token correcto del producto.

• El token sigue siendo válido y la cuenta puede acceder al contenido solicitado.

• Jira usa read:jira-work y no solo los permisos granulares de Jira.

• Confluence tiene los tres permisos que se indican más arriba.

• El host MCP se reinició después de sustituir un token.

Los tokens con permisos deben usar las pasarelas de producto de Atlassian:

https://api.atlassian.com/ex/jira/{cloudId}
https://api.atlassian.com/ex/confluence/{cloudId}

Este servidor usa el tenant Cloud ID fijo en src/atlassian.mjs.

Certificados corporativos

Los productos de inspección TLS, como Zscaler, vuelven a firmar el tráfico HTTPS con una autoridad de certificación corporativa. Es posible que Windows confíe en esa autoridad mientras que Node.js siga usando su propia lista de CA. En las versiones compatibles de Node.js, mantén lo siguiente en el entorno de MCP:

NODE_OPTIONS=--use-system-ca

Si es necesario, exporta la CA corporativa no caducada en formato PEM con codificación Base64 y establece NODE_EXTRA_CA_CERTS en su ruta absoluta. Nunca deshabilites la comprobación TLS.

WSL tiene un almacén de confianza de Linux independiente. Exporta los certificados corporativos raíz e intermedio aplicables desde Windows, guárdalos con la extensión .crt, cópialos a /usr/local/share/ca-certificates/ y ejecuta:

sudo update-ca-certificates

Reinicia WSL antes de probar de nuevo curl, Docker, Node.js u otros clientes HTTPS.

WSL y sistemas sin interfaz gráfica

Si no hay un llavero de escritorio disponible, usa los archivos de token restringidos:

mkdir -p ~/.config
install -m 600 /dev/null ~/.config/atlassian-jira-token
install -m 600 /dev/null ~/.config/atlassian-confluence-token
read -rsp "Jira API token: " token; echo
printf '%s' "$token" > ~/.config/atlassian-jira-token
read -rsp "Confluence API token: " token; echo
printf '%s' "$token" > ~/.config/atlassian-confluence-token
unset token

Configura estas variables en el entorno de MCP:

ATLASSIAN_USER_EMAIL
ATLASSIAN_JIRA_TOKEN_FILE
ATLASSIAN_CONFLUENCE_TOKEN_FILE

ATLASSIAN_JIRA_API_TOKEN y ATLASSIAN_CONFLUENCE_API_TOKEN son compatibles para usos de CI con permisos por proceso, pero no deben permanecer en la configuración de escritorio.

Rotar o eliminar credenciales

Reemplaza los tokens guardados:

npm run configure -- jira
npm run configure -- confluence

Elimina los tokens guardados:

npm run configure -- jira delete
npm run configure -- confluence delete

La eliminación local no revoca un token. Revócalo de forma independiente desde la página de gestión de tokens de Atlassian.

Límite de seguridad

Este proyecto usa defensa en profundidad:

• Control por token: los tokens documentados solo contienen permisos de lectura de Atlassian, por lo que Atlassian no autoriza escrituras.

• Control por implementación: solo se exponen cuatro herramientas de lectura específicas. Sus URL y su método HTTP son fijos; los llamantes no pueden elegir otro host, endpoint ni método.

• Controles de respuesta: las respuestas están limitadas en tamaño, los posibles secretos se ocultan y las proyecciones pueden minimizar los datos devueltos.

Los tokens siguen heredando la visibilidad del creador: la MCP solo puede leer contenido al que esa cuenta ya tiene acceso. Proporcionar un token con más permisos debilita la capa de token, pero no añade operaciones de escritura a este servidor.

Licencia

MIT