atlassian-mcp

Un servidor Model Context Protocol (MCP) para Jira autoalojado (Server / Data Center) y Bitbucket autoalojado (Server / Data Center). Expone herramientas para flujos de trabajo en lenguaje natural en torno a tickets, pull requests, hilos de revisión y contexto de git.

Nota: Este servidor solo admite instancias autoalojadas. Jira Cloud y Bitbucket Cloud usan APIs diferentes y no son compatibles.

Herramientas

Flujo de trabajo

Git

Jira

Bitbucket

Ejemplos de lenguaje natural

• "¿en qué estoy trabajando?" → get_dev_context

• "crea una rama para FOO-123" → start_work

• "publica esto / fusiona y cierra el ticket" → complete_work

• "muestra mis PRs pendientes de revisión" → bitbucket_search with mine=true

• "lista los PRs abiertos de este repositorio desde feature/ABC-123" → bitbucket_search with fromBranch

• "dame una visión completa del PR 42" → bitbucket_get_pr

• "abre un PR desde mi rama actual a master" → bitbucket_mutate with create

• "aprobar / fusionar / rechazar el PR 42" → bitbucket_mutate with action

• "responder al comentario 123 en el PR 42" → bitbucket_comment with commentId=123

• "resolver este bloqueador en el PR 42" → bitbucket_comment with action=update, severity=BLOCKER, state=RESOLVED

• "listar las tareas de la lista de verificación del PR" → bitbucket_pr_tasks with action=list

• "encontrar bugs asignados a mí en el proyecto PAY" → jira_search with mine=true, issueType=Bug

• "¿qué hay en el sprint actual?" → jira_search with resource=board_overview

• "mover FOO-123 a In Progress" → jira_mutate with transitionName="In Progress"

• "registrar 2h en FOO-123" → jira_mutate with worklog

• "crear la versión 9.1.0 en PAY" → jira_version with action=create, projectKey=PAY, name=9.1.0

• "listar los lanzamientos de PAY" → jira_search with resource=versions, project=PAY

• "publicar la versión 12345" → jira_version with action=release, id=12345

• "establecer la versión de corrección 9.1.0 en FOO-123" → jira_mutate with update.fixVersion=9.1.0

• "crear una tarea bajo la épica FOO-100" → jira_mutate with create.issueType=Task, create.parent=FOO-100 (detecta automáticamente la épica y establece Epic Link)

• "mover FOO-123 bajo la épica FOO-100" → jira_mutate with update.epicLink=FOO-100

• "crear una épica" → jira_mutate with create.issueType=Epic (Epic Name se establece por defecto al resumen)

• "establecer los story points en 5" → jira_mutate with update.customFields={"Story Points": 5} — los valores son simples (etiqueta de opción, nombre de usuario, fecha, array de etiquetas); el servidor los envuelve según el esquema del campo

• "¿qué puedo establecer en este ticket / en una épica?" → jira_search resource=fields with issueKey=FOO-123 (pantalla de edición) o project=FOO+issueType=Epic (pantalla de creación): campos obligatorios y opcionales, formas de los valores, valores permitidos

Related MCP server: Bitbucket Server MCP

Configuración

1. Crea un archivo de configuración

Crea ~/.atlassian-mcp.json:

{
  "$schema": "https://raw.githubusercontent.com/stubbedev/atlassian-mcp/master/atlassian-mcp.schema.json",
  "jira": {
    "url": "https://jira.example.com",
    "token": "your-jira-personal-access-token"
  },
  "bitbucket": {
    "url": "https://bitbucket.example.com",
    "token": "your-bitbucket-personal-access-token"
  }
}

El campo $schema es opcional, pero permite el autocompletado y la validación en el editor.

• projectKey significa un código de proyecto:

  • Ejemplo de Jira: PAY en el ticket PAY-123

  • Ejemplo de Bitbucket: proyecto ENG en la ruta de repositorio ENG/payments-service

• También puedes usar alias ergonómicos:

  • Jira: project (alias de projectKey)

  • Bitbucket: project y repo (alias de projectKey y repoSlug)

• Para las herramientas de Bitbucket, projectKey y repoSlug se suelen detectar automáticamente desde tu remoto origin local.

• bitbucket_create_pull_request también detecta automáticamente fromBranch desde tu rama actual y devuelve el PR abierto existente si ya hay uno para esa rama.

• Las llamadas de Jira con ámbito de proyecto aceptan projectKey y funcionan mejor cuando se proporciona.

• Si se omite projectKey para la creación de incidencias o la consulta de tipos en Jira, el servidor intenta inferirlo a partir de la clave de ticket de tu rama actual; si solo hay un proyecto visible, recurre a la selección automática; de lo contrario, devuelve una lista numerada de proyectos para elegir.

Alternativamente, usa variables de entorno (o un archivo .env en este directorio):

JIRA_URL=https://jira.example.com
JIRA_ACCESS_TOKEN=your-jira-personal-access-token
BITBUCKET_URL=https://bitbucket.example.com
BITBUCKET_ACCESS_TOKEN=your-bitbucket-personal-access-token

La configuración se resuelve en este orden: argumento CLI --config <path> → variable de entorno ATLASSIAN_MCP_CONFIG → ~/.atlassian-mcp.json → $XDG_CONFIG_HOME/atlassian-mcp/config.json (por defecto ~/.config/atlassian-mcp/config.json) → .atlassian-mcp.json en el directorio de trabajo actual → variables de entorno.

2. Conecta a tu herramienta de IA

No se requiere clonar ni compilar: solo apunta tu herramienta a npx @stubbedev/atlassian-mcp@latest y se instalará y ejecutará automáticamente.

Nota: --prefer-online puede romper el inicio de MCP en algunos clientes. Mantén el comando simple y usa los pasos de actualización a continuación cuando quieras actualizar.

Claude Code

claude mcp add atlassian -- npx -y @stubbedev/atlassian-mcp@latest --config ~/.atlassian-mcp.json

Cursor

Añade a ~/.cursor/mcp.json (global) o .cursor/mcp.json (solo proyecto):

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/Users/you/.atlassian-mcp.json"]
    }
  }
}

Windsurf

Añade a ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/Users/you/.atlassian-mcp.json"]
    }
  }
}

Zed

Añade a ~/.config/zed/settings.json:

{
  "context_servers": {
    "atlassian": {
      "command": {
        "path": "npx",
        "args": ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/home/you/.atlassian-mcp.json"]
      }
    }
  }
}

OpenCode

Añade a opencode.json en la raíz de tu proyecto (o ~/.config/opencode/opencode.json para global):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "atlassian": {
      "type": "local",
      "command": ["npx", "-y", "@stubbedev/atlassian-mcp@latest", "--config", "/home/you/.atlassian-mcp.json"]
    }
  }
}

Codex CLI

Añade a ~/.codex/config.yaml:

mcpServers:
  atlassian:
    command: npx
    args:
      - -y
      - @stubbedev/atlassian-mcp@latest
      - --config
      - /home/you/.atlassian-mcp.json

Cualquier otra herramienta compatible con MCP

La mayoría de las herramientas que admiten MCP aceptan el mismo formato JSON. Usa npx como comando con ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/path/to/config.json"] como argumentos.

Actualizar instalaciones existentes

Si tu cliente MCP ya está configurado y quieres la versión más reciente del paquete:

npx clear-npx-cache

A continuación, reinicia tu cliente MCP.

Instalar sin npm

El servidor es un único binario estático de Go. La ruta con npx de arriba descarga el binario precompilado para tu plataforma en la primera ejecución; estas alternativas omiten Node por completo:

# Go toolchain — installs to $GOBIN / $GOPATH/bin
go install github.com/stubbedev/atlassian-mcp@latest

# Nix flake
nix run github:stubbedev/atlassian-mcp -- --config ~/.atlassian-mcp.json

Luego apunta el command de tu cliente MCP al binario atlassian-mcp resultante, en lugar de npx. En estas rutas, ffmpeg/ffprobe deben estar disponibles en PATH (o define ATLASSIAN_MCP_FFMPEG_PATH / ATLASSIAN_MCP_FFPROBE_PATH); el envoltorio de npm los incluye automáticamente.

Ejecutar como servidor HTTP (compartido / detrás de un proxy)

Por defecto, el servidor habla MCP sobre stdio (un proceso por cliente, lanzado por tu editor). También puede ejecutarse como un servidor Streamable HTTP de larga duración que comparten muchos clientes, útil detrás de un proxy inverso:

atlassian-mcp --http                 # binds 127.0.0.1:7337
atlassian-mcp --http 127.0.0.1:9000  # custom address
ATLASSIAN_MCP_HTTP=1 atlassian-mcp   # same, via env

• Un único endpoint POST /mcp (JSON-RPC) más un flujo SSE opcional GET /mcp que transporta las peticiones servidor→cliente (roots/list, elicitación). El servidor es con estado: initialize crea una sesión y devuelve una cabecera Mcp-Session-Id, que el cliente debe repetir en cada petición posterior y en el flujo SSE. Las peticiones con un id de sesión ausente/desconocido/expirado reciben un HTTP 404 para que el cliente se reinicialice (comportamiento estándar de los clientes MCP). Cada cliente/worktree conectado es una sesión aislada.

• Autenticación: en un enlace de loopback no se necesita token. Enlazar una dirección que no sea loopback requiere ATLASSIAN_MCP_HTTP_TOKEN (los clientes lo envían como Authorization: Bearer …); de lo contrario, el servidor se niega a arrancar. Termina la TLS en tu proxy.

• GET /healthz es una sonda de actividad sin autenticar (devuelve ok) para proxies/balanceadores de carga. Las sesiones inactivas se eliminan a después de 1 h.

El contexto del repositorio proviene del cliente, no del directorio de trabajo del servidor. Las herramientas que necesitan un repositorio (las herramientas git_*, get_dev_context, start_work, complete_work y la auto-detección de proyecto/repositorio de Bitbucket) lo resuelven en este orden: un argumento repoPath explícito → una raíz fijada mediante cabecera de petición (ver debajo) → las raíces del espacio de trabajo MCP del cliente (el servidor lo pide vía roots/list, las caché por sesión y las refresca con notifications/roots/list_changed) → el cwd del proceso (solo stdio). Así, un servidor HTTP compartido único maneja muchos worktrees: el workspace de cada cliente dirige sus llamadas. Cuando una sesión expone varias raíces (múltiples worktrees), una herramienta sin repoPath usa la primera raíz que sea un repositorio git; pasa repoPath (una ruta absoluta o un nombre/basename de worktree que coincida con una de las raíces) para dirigirte a un worktree concreto. Para Bitbucket, pasar projectKey+repoSlug explícitamente omite por completo la detección de repositorios. Los repositorios deben ser accesibles desde el host del servidor (las herramientas git ejecutan git localmente).

Fijar la raíz a través de una cabecera de petición (HTTP). Un proxy inverso o un harness que ya conozca el árbol de trabajo puede pasárselo directamente al servidor, evitando ir y volver con roots/list (y funcionando incluso cuando el cliente nunca anunció la capability roots). Envía un URI file:// o una ruta absoluta (separadas por comas para varias; gana la primera git repo):

X-Mcp-Root: file:///srv/myrepo
X-Mcp-Roots: /srv/a, /srv/b

Nombres de cabecera aceptados: X-Mcp-Roots, X-Mcp-Root, Mcp-Roots, Mcp-Root. El valor de una cabecera es autoritativo: prevalece sobre roots/list y sobrevive a list_changed.

Configuración de cliente para un servidor HTTP ya en marcha (ejemplo te con Claude Code):

claude mcp add --transport http atlassian http://127.0.0.1:7337/mcp

Proceso de decodificación de archivos adjuntos

Las herramientas de adjuntos (jira_get_attachment, bitbucket_get_attachment) decodifican los adjuntos binarios en contenido legible por el modelo antes de devolverlos:

Los archivos guardados automáticamente se cortan de forma periódica por TTL y cuota de tamaño total; consulta Anulaciones de entorno más abajo.

Herramientas externas (opcionales)

La decodificación de imágenes y del texto de los PDF es Go puro y no necesita nada posterior a su instalación. Las dos tuberías que no tienen implementación en Go puro llaman a binarios externos:

• ffmpeg + ffprobe — muestreo de fotogramas de vídeo e imágenes animadas. El envoltorio de npm incluye ffmpeg-static / ffprobe-static e inyecta sus rutas, así que el camino de instalación con npx no requiere configuración. En las rutas de go install / Nix, instala ffmpeg (que incluye ffprobe) o define las variables de entorno de abajo.

• pdftoppm (poppler) o mutool (MuPDF) — solo se necesitan para rasterizar los PDFs escaneados sin texto extraíble. Si, si no encuentras ninguno en PATH, esos PDFs se guardan en disco.

Anulaciones de entorno

Lanzamientos (Mantenedores)

Este paquete se publica en npm como @stubbedev/atlassian-mcp.

Usa versionado semántico para los lanzamientos. Los cambios que afecten a la superficie de las herramientas deben incrementar la versión múltiple mientras sea <1.0.0 (por ejemplo, 0.0.x -> 0.1.0).

Al hacer push de un tag v*, .github/workflows/publish.yml recopila de manera cruzada el binario de Go para 14 plataformas/arquitecturas, lo adjunta a un release de GitHub y publica el envoltorio npm (que descarga el binario correspondiente al instalar).

Flujo de lanzamiento:

# choose one: patch | minor | major (also: npm run release:patch / :minor / :major)
npm version patch          # bumps package.json, commits, tags vX.Y.Z
git push origin HEAD --follow-tags

flake.nix lee su versión desde package.json, por lo que el paquete Nix sigue automáticamente esa subida de versión. GitHub Actions compiles + publica a partir del tag enviado.

• El flujo de trabajo está configurado para npm Trusted Publisher (OIDC), por lo que no se necesita secreto NPM_TOKEN

Configuración npm necesaria (una sola vez):

• En los ajustes del paquete npm, añade este repo/flujo de GitHub como Trusted Publisher.

Creación de tokens de acceso personal

Jira Server / Data Center

Los tokens de acceso personal están soportados a a partir de Jira 8.14.

1. Inicia sesión en tu instancia de Jira.

2. Haz clic en el avatar de tu perfil en la esquina superior derecha y selecciona Perfil.

3. En la barra lateral izquierda, haz clic en Tokens de acceso personal.

4. Haz clic en Crear token.

5. Ponle un nombre al token (por ejemplo, atlassian-mcp) y, si quieres, fija una fecha de caducidad.

6. Haz clic en Crear y copia el token; solo se mostrará una vez.

Pega el token como el valor token bajo jira en tu archivo de configuración.

Si tu versión de Jira es anterior a 8.14, puedes usar HTTP Basic Auth en su lugar, pero este servidor solo admite autenticación con token Bearer (PAT).

Bitbucket Server / Data Center

Los tokens de acceso personal están soportados desde Bitbucket Server 5.5.

1. Inicia sesión en tu instancia de Bitbucket.

2. Haz clic en el avatar de tu perfil en la esquina superior derecha y selecciona Administrar cuenta.

3. En la barra lateral izquierda, bajo Seguridad, haz clic en Tokens de acceso personal.

4. Haz clic en Crear un token.

5. Ponle un nombre al token (por ejemplo, atlassian-mcp).

6. Configura los permisos:

   • Proyectos: Lectura

   • Repositorios: Lectura + Escritura (la escritura es necesaria para crear pull requests y añadir comentarios)

7. Opcionalmente, fija una fecha de caducidad.

8. Haz clic en Crear y copia el token; solo se mostrará una vez.

Pega el token como el valor token bajo bitbucket en tu archivo de configuración.

Desarrollo

El servidor es un único módulo de Go en la raíz del repositorio (sin árbol src/).

# Build the binary
go build -o atlassian-mcp .

# Run it
./atlassian-mcp --config /path/to/config.json

# Vet + unit tests
go vet ./...
go test ./...

# Test the tool list
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | ./atlassian-mcp

# Quick release smoke check (build + tools/list validation)
npm run smoke