MCP Atlassian

Name: MCP Atlassian
Author: sooperset

Versión de PyPI PyPI - Descargas Ejecutar pruebas Licencia

Servidor de Protocolo de Contexto de Modelo (MCP) para productos de Atlassian (Confluence y Jira). Esta integración es compatible con las implementaciones de Confluence y Jira Cloud y de servidor/centro de datos.

Ejemplo de uso

Pídale a su asistente de IA que:

Actualizaciones automáticas de Jira : "Actualizar Jira desde las notas de la reunión"
Búsqueda en Confluence con IA : "Encuentra nuestra guía OKR en Confluence y resúmela"
Filtrado inteligente de incidencias de Jira : "Muéstrame errores urgentes en el proyecto PROJ de la semana pasada"
📄 Creación y gestión de contenido : "Crear un documento de diseño técnico para la función XYZ"

Demostración de funciones

https://github.com/user-attachments/assets/35303504-14c6-4ae4-913b-7c25ea511c3e

https://github.com/user-attachments/assets/7fe9c488-ad0c-4876-9b54-120b666bb785

Compatibilidad

Producto	Tipo de implementación	Estado de soporte
Confluencia	Nube	✅ Totalmente compatible
Confluencia	Servidor/Centro de datos	✅ Compatible (versión 6.0+)
Jira	Nube	✅ Totalmente compatible
Jira	Servidor/Centro de datos	✅ Compatible (versión 8.14+)

Related MCP server: MCP Atlassian

Guía de inicio rápido

🔐 1. Configuración de autenticación

MCP Atlassian admite tres métodos de autenticación:

A. Autenticación mediante token API (nube)

Vaya a https://id.atlassian.com/manage-profile/security/api-tokens
Haga clic en Crear token de API y asígnele un nombre.
Copiar el token inmediatamente

B. Token de acceso personal (Servidor/Centro de datos)

Vaya a su perfil (avatar) → Perfil → Tokens de acceso personal
Haga clic en Crear token , asígnele un nombre y configure la fecha de caducidad.
Copiar el token inmediatamente

C. Autenticación OAuth 2.0 (nube)

Vaya a la consola para desarrolladores de Atlassian
Crear una aplicación de "integración OAuth 2.0 (3LO)"
Configurar permisos (ámbitos) para Jira/Confluence
Establecer URL de devolución de llamada (por ejemplo, http://localhost:8080/callback )
Ejecutar el asistente de configuración:
docker run --rm -i \ -p 8080:8080 \ -v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian" \ ghcr.io/sooperset/mcp-atlassian:latest --oauth-setup -v
Siga las indicaciones para Client ID , Secret , URI y Scope
Autorización completa del navegador
Agregue las credenciales obtenidas a .env o a la configuración IDE:
- ATLASSIAN_OAUTH_CLOUD_ID (del asistente)
- ATLASSIAN_OAUTH_CLIENT_ID
- ATLASSIAN_OAUTH_CLIENT_SECRET
- ATLASSIAN_OAUTH_REDIRECT_URI
- ATLASSIAN_OAUTH_SCOPE

[!IMPORTANTE] Incluir offline_access en el alcance para la autenticación persistente (por ejemplo, read:jira-work write:jira-work offline_access )

📦 2. Instalación

MCP Atlassian se distribuye como una imagen de Docker. Esta es la forma recomendada de ejecutar el servidor, especialmente para la integración con IDE. Asegúrese de tener Docker instalado.

# Pull Pre-built Image docker pull ghcr.io/sooperset/mcp-atlassian:latest

🛠️ Integración IDE

MCP Atlassian está diseñado para usarse con asistentes de IA a través de la integración IDE.

TIP

Para Claude Desktop : Localice y edite el archivo de configuración directamente:

Ventanas : %APPDATA%\Claude\claude_desktop_config.json
macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
Linux : ~/.config/Claude/claude_desktop_config.json

Para el cursor : Abra Configuración → MCP → + Agregar nuevo servidor MCP global

⚙️ Métodos de configuración

Hay dos enfoques principales para configurar el contenedor Docker:

Pasar variables directamente (mostradas en los ejemplos a continuación)
Uso de un archivo de entorno con el indicador --env-file (mostrado en secciones plegables)

[!NOTA] Las variables de entorno comunes incluyen:
CONFLUENCE_SPACES_FILTER : Filtrar por claves de espacio (p. ej., "DEV,TEAM,DOC")
JIRA_PROJECTS_FILTER : Filtrar por claves de proyecto (p. ej., "PROJ,DEV,SUPPORT")
READ_ONLY_MODE : Establézcalo en "verdadero" para deshabilitar las operaciones de escritura
MCP_VERBOSE : Establézcalo en "verdadero" para un registro más detallado
ENABLED_TOOLS : Lista separada por comas de nombres de herramientas para habilitar (por ejemplo, "confluence_search,jira_get_issue")
Consulte el archivo .env.example para ver todas las opciones disponibles.

📝 Ejemplos de configuración

Método 1 (Pasar variables directamente):

{ "mcpServers": { "mcp-atlassian": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "CONFLUENCE_URL", "-e", "CONFLUENCE_USERNAME", "-e", "CONFLUENCE_API_TOKEN", "-e", "JIRA_URL", "-e", "JIRA_USERNAME", "-e", "JIRA_API_TOKEN", "ghcr.io/sooperset/mcp-atlassian:latest" ], "env": { "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki", "CONFLUENCE_USERNAME": "your.email@company.com", "CONFLUENCE_API_TOKEN": "your_confluence_api_token", "JIRA_URL": "https://your-company.atlassian.net", "JIRA_USERNAME": "your.email@company.com", "JIRA_API_TOKEN": "your_jira_api_token" } } } }

{ "mcpServers": { "mcp-atlassian": { "command": "docker", "args": [ "run", "--rm", "-i", "--env-file", "/path/to/your/mcp-atlassian.env", "ghcr.io/sooperset/mcp-atlassian:latest" ] } } }

Para implementaciones de servidor/centro de datos, utilice el paso directo de variables:

{ "mcpServers": { "mcp-atlassian": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "CONFLUENCE_URL", "-e", "CONFLUENCE_PERSONAL_TOKEN", "-e", "CONFLUENCE_SSL_VERIFY", "-e", "JIRA_URL", "-e", "JIRA_PERSONAL_TOKEN", "-e", "JIRA_SSL_VERIFY", "ghcr.io/sooperset/mcp-atlassian:latest" ], "env": { "CONFLUENCE_URL": "https://confluence.your-company.com", "CONFLUENCE_PERSONAL_TOKEN": "your_confluence_pat", "CONFLUENCE_SSL_VERIFY": "false", "JIRA_URL": "https://jira.your-company.com", "JIRA_PERSONAL_TOKEN": "your_jira_pat", "JIRA_SSL_VERIFY": "false" } } } }

NOTE

EstablezcaCONFLUENCE_SSL_VERIFY y JIRA_SSL_VERIFY en "falso" solo si tiene certificados autofirmados.

Este ejemplo muestra cómo configurar mcp-atlassian en su IDE (como Cursor o Claude Desktop) al usar OAuth 2.0 para Atlassian Cloud. Asegúrese de haber completado primero el asistente de configuración de OAuth .

{ "mcpServers": { "mcp-atlassian": { "command": "docker", "args": [ "run", "--rm", "-i", "-v", "<path_to_your_home>/.mcp-atlassian:/home/app/.mcp-atlassian", "-e", "JIRA_URL", "-e", "CONFLUENCE_URL", "-e", "ATLASSIAN_OAUTH_CLIENT_ID", "-e", "ATLASSIAN_OAUTH_CLIENT_SECRET", "-e", "ATLASSIAN_OAUTH_REDIRECT_URI", "-e", "ATLASSIAN_OAUTH_SCOPE", "-e", "ATLASSIAN_OAUTH_CLOUD_ID", "ghcr.io/sooperset/mcp-atlassian:latest", ], "env": { "JIRA_URL": "https://your-company.atlassian.net", "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki", "ATLASSIAN_OAUTH_CLIENT_ID": "YOUR_OAUTH_APP_CLIENT_ID", "ATLASSIAN_OAUTH_CLIENT_SECRET": "YOUR_OAUTH_APP_CLIENT_SECRET", "ATLASSIAN_OAUTH_REDIRECT_URI": "http://localhost:8080/callback", "ATLASSIAN_OAUTH_SCOPE": "read:jira-work write:jira-work read:confluence-content.all write:confluence-content offline_access", "ATLASSIAN_OAUTH_CLOUD_ID": "YOUR_CLOUD_ID_FROM_SETUP_WIZARD" } } } }

[!NOTA]
ATLASSIAN_OAUTH_CLOUD_ID se obtiene de la salida del asistente --oauth-setup .
Otras variables ATLASSIAN_OAUTH_* son aquellas que usted configuró para su aplicación OAuth en Atlassian Developer Console (y usó como entrada para el asistente de configuración).
Aún se requieren JIRA_URL y CONFLUENCE_URL para sus instancias de Cloud.

MCP Atlassian admite el enrutamiento de solicitudes de API mediante servidores proxy HTTP/HTTPS/SOCKS estándar. Configure mediante variables de entorno:

Admite los estándares HTTP_PROXY , HTTPS_PROXY , NO_PROXY y SOCKS_PROXY .
Están disponibles anulaciones específicas del servicio (por ejemplo, JIRA_HTTPS_PROXY , CONFLUENCE_NO_PROXY ).
Las variables específicas del servicio anulan las globales para ese servicio.

Agregue las variables proxy relevantes a las secciones args (usando -e ) y env de su configuración de MCP:

{ "mcpServers": { "mcp-atlassian": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "... existing Confluence/Jira vars", "-e", "HTTP_PROXY", "-e", "HTTPS_PROXY", "-e", "NO_PROXY", "ghcr.io/sooperset/mcp-atlassian:latest" ], "env": { "... existing Confluence/Jira vars": "...", "HTTP_PROXY": "http://proxy.internal:8080", "HTTPS_PROXY": "http://proxy.internal:8080", "NO_PROXY": "localhost,.your-company.com" } } } }

Las credenciales de las URL de proxy se ocultan en los registros. Si se configura NO_PROXY , se respetará para las solicitudes a los hosts que coincidan.

Solo para Confluence Cloud:

{ "mcpServers": { "mcp-atlassian": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "CONFLUENCE_URL", "-e", "CONFLUENCE_USERNAME", "-e", "CONFLUENCE_API_TOKEN", "ghcr.io/sooperset/mcp-atlassian:latest" ], "env": { "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki", "CONFLUENCE_USERNAME": "your.email@company.com", "CONFLUENCE_API_TOKEN": "your_api_token" } } } }

Para Confluence Server/DC, utilice:

{ "mcpServers": { "mcp-atlassian": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "CONFLUENCE_URL", "-e", "CONFLUENCE_PERSONAL_TOKEN", "ghcr.io/sooperset/mcp-atlassian:latest" ], "env": { "CONFLUENCE_URL": "https://confluence.your-company.com", "CONFLUENCE_PERSONAL_TOKEN": "your_personal_token" } } } }

Solo para Jira Cloud:

{ "mcpServers": { "mcp-atlassian": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "JIRA_URL", "-e", "JIRA_USERNAME", "-e", "JIRA_API_TOKEN", "ghcr.io/sooperset/mcp-atlassian:latest" ], "env": { "JIRA_URL": "https://your-company.atlassian.net", "JIRA_USERNAME": "your.email@company.com", "JIRA_API_TOKEN": "your_api_token" } } } }

Para Jira Server/DC, utilice:

{ "mcpServers": { "mcp-atlassian": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "JIRA_URL", "-e", "JIRA_PERSONAL_TOKEN", "ghcr.io/sooperset/mcp-atlassian:latest" ], "env": { "JIRA_URL": "https://jira.your-company.com", "JIRA_PERSONAL_TOKEN": "your_personal_token" } } } }

👥 Configuración del transporte HTTP

En lugar de utilizar stdio , puede ejecutar el servidor como un servicio HTTP persistente utilizando:

Transporte sse (eventos enviados por el servidor) en el punto final /sse
transporte streamable-http en el punto final /mcp

Ambos tipos de transporte admiten la autenticación de usuario único y multiusuario:

Opciones de autenticación:

Usuario único : utilice la autenticación a nivel de servidor configurada a través de variables de entorno
Multiusuario : cada usuario proporciona su propia autenticación:
- Nube: Tokens portadores OAuth 2.0
- Servidor/Centro de datos: Tokens de acceso personal (PAT)

Inicie el servidor con el transporte elegido:
# For SSE transport docker run --rm -p 9000:9000 \ --env-file /path/to/your/.env \ ghcr.io/sooperset/mcp-atlassian:latest \ --transport sse --port 9000 -vv # OR for streamable-http transport docker run --rm -p 9000:9000 \ --env-file /path/to/your/.env \ ghcr.io/sooperset/mcp-atlassian:latest \ --transport streamable-http --port 9000 -vv
Configurar su IDE (ejemplo de usuario único):
Ejemplo de transporte SSE:
{ "mcpServers": { "mcp-atlassian-http": { "url": "http://localhost:9000/sse" } } }
Ejemplo de transporte HTTP transmisible:
{ "mcpServers": { "mcp-atlassian-service": { "url": "http://localhost:9000/mcp" } } }

A continuación se muestra un ejemplo completo de configuración de la autenticación multiusuario con transporte HTTP transmitible:

Primero, ejecute el asistente de configuración de OAuth para configurar las credenciales de OAuth del servidor:
docker run --rm -i \ -p 8080:8080 \ -v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian" \ ghcr.io/sooperset/mcp-atlassian:latest --oauth-setup -v
Inicie el servidor con transporte HTTP transmitible:
docker run --rm -p 9000:9000 \ --env-file /path/to/your/.env \ ghcr.io/sooperset/mcp-atlassian:latest \ --transport streamable-http --port 9000 -vv
Configure los ajustes MCP de su IDE:

Elija el método de autorización adecuado para su implementación de Atlassian:

Nube (OAuth 2.0): use esta opción si su organización está en Atlassian Cloud y tiene un token de acceso OAuth para cada usuario.
Servidor/Centro de datos (PAT): use esto si está en un servidor o centro de datos de Atlassian y cada usuario tiene un token de acceso personal (PAT).

Ejemplo de nube (OAuth 2.0):

{ "mcpServers": { "mcp-atlassian-service": { "url": "http://localhost:9000/mcp", "headers": { "Authorization": "Bearer <USER_OAUTH_ACCESS_TOKEN>" } } } }

Ejemplo de servidor/centro de datos (PAT):

{ "mcpServers": { "mcp-atlassian-service": { "url": "http://localhost:9000/mcp", "headers": { "Authorization": "Token <USER_PERSONAL_ACCESS_TOKEN>" } } } }

Variables de entorno requeridas en .env :
JIRA_URL=https://your-company.atlassian.net CONFLUENCE_URL=https://your-company.atlassian.net/wiki ATLASSIAN_OAUTH_CLIENT_ID=your_oauth_app_client_id ATLASSIAN_OAUTH_CLIENT_SECRET=your_oauth_app_client_secret ATLASSIAN_OAUTH_REDIRECT_URI=http://localhost:8080/callback ATLASSIAN_OAUTH_SCOPE=read:jira-work write:jira-work read:confluence-content.all write:confluence-content offline_access ATLASSIAN_OAUTH_CLOUD_ID=your_cloud_id_from_setup_wizard

[!NOTA]
El servidor debe tener configurada su propia autenticación de respaldo (p. ej., mediante variables de entorno para el token de API, PAT o su propia configuración de OAuth mediante --oauth-setup). Esto se utiliza si una solicitud no incluye autenticación específica del usuario.
OAuth : cada usuario necesita su propio token de acceso OAuth desde su aplicación Atlassian OAuth.
PAT : Cada usuario proporciona su propio token de acceso personal.
El servidor utilizará el token del usuario para las llamadas API cuando se proporcione, recurriendo a la autenticación del servidor si no lo está.
Los tokens de usuario deben tener alcances apropiados para las operaciones necesarias

Herramientas

Herramientas clave

Herramientas de Jira

jira_get_issue : obtener detalles de un problema específico
jira_search : Problemas de búsqueda con JQL
jira_create_issue : Crea un nuevo problema
jira_update_issue : Actualizar un problema existente
jira_transition_issue : Transición de un problema a un nuevo estado
jira_add_comment : Agregar un comentario a un problema

Herramientas de Confluence

confluence_search : busca contenido de Confluence usando CQL
confluence_get_page : Obtener el contenido de una página específica
confluence_create_page : Crea una nueva página
confluence_update_page : Actualizar una página existente

Operación	Herramientas de Jira	Herramientas de Confluence
Leer	`jira_search`	`confluence_search`
	`jira_get_issue`	`confluence_get_page`
	`jira_get_project_issues`	`confluence_get_page_children`
	`jira_get_worklog`	`confluence_get_comments`
	`jira_get_transitions`	`confluence_get_labels`
	`jira_get_agile_boards`
	`jira_get_board_issues`
	`jira_get_sprints_from_board`
	`jira_get_sprint_issues`
	`jira_get_issue_link_types`
	`jira_batch_get_changelogs` *
	`jira_get_user_profile`
	`jira_download_attachments`
Escribir	`jira_create_issue`	`confluence_create_page`
	`jira_update_issue`	`confluence_update_page`
	`jira_delete_issue`	`confluence_delete_page`
	`jira_batch_create_issues`	`confluence_add_label`
	`jira_add_comment`	`confluence_add_comment`
	`jira_transition_issue`
	`jira_add_worklog`
	`jira_link_to_epic`
	`jira_create_sprint`
	`jira_update_sprint`
	`jira_create_issue_link`
	`jira_remove_issue_link`

*Herramienta disponible únicamente en Jira Cloud

Filtrado de herramientas y control de acceso

El servidor proporciona dos formas de controlar el acceso a las herramientas:

Filtrado de herramientas : utilice el indicador --enabled-tools o la variable de entorno ENABLED_TOOLS para especificar qué herramientas deben estar disponibles:
# Via environment variable ENABLED_TOOLS="confluence_search,jira_get_issue,jira_search" # Or via command line flag docker run ... --enabled-tools "confluence_search,jira_get_issue,jira_search" ...
Control de lectura/escritura : Las herramientas se clasifican como operaciones de lectura o escritura. Cuando READ_ONLY_MODE está habilitado, solo están disponibles las operaciones de lectura, independientemente de la configuración ENABLED_TOOLS .

Solución de problemas y depuración

Problemas comunes

Errores de autenticación :
- Para la nube: Verifique sus tokens API (no la contraseña de su cuenta)
- Para servidor/centro de datos: Verifique que su token de acceso personal sea válido y no esté vencido
- Para servidores Confluence más antiguos: Algunas versiones anteriores requieren autenticación básica con CONFLUENCE_USERNAME y CONFLUENCE_API_TOKEN (donde token es su contraseña)
Problemas con el certificado SSL : si usa un servidor o centro de datos y encuentra errores de SSL, configure CONFLUENCE_SSL_VERIFY=false o JIRA_SSL_VERIFY=false
Errores de permisos : asegúrese de que su cuenta de Atlassian tenga permisos suficientes para acceder a los espacios/proyectos

Herramientas de depuración

# Using MCP Inspector for testing npx @modelcontextprotocol/inspector uvx mcp-atlassian ... # For local development version npx @modelcontextprotocol/inspector uv --directory /path/to/your/mcp-atlassian run mcp-atlassian ... # View logs # macOS tail -n 20 -f ~/Library/Logs/Claude/mcp*.log # Windows type %APPDATA%\Claude\logs\mcp*.log | more

Seguridad

Nunca comparta tokens API
Mantenga los archivos .env seguros y privados
Consulte SECURITY.md para conocer las mejores prácticas

Contribuyendo

¡Agradecemos sus contribuciones a MCP Atlassian! Si desea contribuir:

Consulte nuestra guía CONTRIBUTING.md para obtener instrucciones detalladas de configuración del desarrollo.
Realizar cambios y enviar una solicitud de extracción.

Usamos ganchos previos a la confirmación para garantizar la calidad del código y seguimos el control de versiones semántico para los lanzamientos.

Licencia

Con licencia del MIT (véase el archivo de LICENCIA ). Este no es un producto oficial de Atlassian.

MCP Atlassian

MCP Atlassian

Ejemplo de uso

Demostración de funciones

Compatibilidad

Guía de inicio rápido

🔐 1. Configuración de autenticación

A. Autenticación mediante token API (nube)

B. Token de acceso personal (Servidor/Centro de datos)

C. Autenticación OAuth 2.0 (nube)

📦 2. Instalación

🛠️ Integración IDE

⚙️ Métodos de configuración

📝 Ejemplos de configuración

👥 Configuración del transporte HTTP

Herramientas

Herramientas clave

Herramientas de Jira

Herramientas de Confluence

Filtrado de herramientas y control de acceso

Solución de problemas y depuración

Problemas comunes

Herramientas de depuración

Seguridad

Contribuyendo

Licencia

Resources

Appeared in Searches

New MCP Servers

Latest Blog Posts

MCP directory API