Servidor MCP de Jira (solo lectura)

Un MCP local que permite a Claude Code obtener contexto de tickets de Jira (detalles de incidencias, hilos de comentarios, el grafo de referencias alrededor de un ticket y resultados de búsqueda JQL) renderizado como Markdown compacto. Los archivos adjuntos de imagen (por ejemplo, la captura de pantalla en un ticket de bug de UI) se pueden recuperar para que Claude los analice visualmente.

Lo que deliberadamente no puede hacer

Este servidor es estrictamente de solo lectura. No expone ninguna herramienta que cree, actualice, transicione, elimine o comente nada. El cumplimiento se aplica en capas:

1. En el código: cada solicitud HTTP pasa por un único helper que solo permite GET, con una excepción en la lista blanca: POST /rest/api/3/search/jql, una operación de lectura que Atlassian exige que se envíe como POST. Cualquier otro método lanza ReadOnlyViolationError, por lo que una futura edición que agregue una llamada de escritura fallará de forma ruidosa.

2. A nivel de credenciales: crea el token de API solo con alcances de lectura (abajo), de modo que incluso un error no pudiera escribir.

Related MCP server: JIRA MCP Server

Herramientas

Configuración

1. Crear un token de API de Atlassian

1. Ve a https://id.atlassian.com/manage-profile/security/api-tokens.

2. Elige Create API token with scopes (Atlassian está deprecando los tokens sin alcances).

3. Selecciona la aplicación Jira y elige solo estos alcances:

   • read:jira-work

   • read:jira-user

4. Copia el token inmediatamente; solo se muestra una vez.

Un token sin alcances más antiguo también funciona; el servidor maneja ambos automáticamente (ver abajo).

2. Configurar .env

cp .env.example .env   # then edit

Claves requeridas (esta es toda la superficie de configuración):

.env está en gitignore; nunca lo confirmes. Las variables de entorno reales tienen prioridad sobre el archivo. El archivo se ubica en relación con el directorio del proyecto (no el directorio de trabajo), por lo que el servidor lo encuentra sin importar desde dónde se lance.

3. Instalar dependencias

Con uv (preferido, ya que este repositorio tiene un uv.lock):

uv sync

O con pip simple en un venv:

python -m venv .venv
.venv/bin/pip install -r requirements.txt   # Windows: .venv\Scripts\pip

4. Verificar con --check

.venv/bin/python -m jira_mcp --check            # connectivity + auth only
.venv/bin/python -m jira_mcp --check PROJ-123   # also fetch a ticket in full

Esto imprime si se encontró .env, qué URL base se seleccionó (y si fue necesario el respaldo de cloud-ID), la cuenta autenticada y, cuando se proporciona una clave, el ticket exactamente como lo vería Claude.

Tokens con alcances vs. sin alcances: el problema de la URL base

• Un token sin alcances funciona contra la URL de tu sitio, https://<site>.atlassian.net.

• Un token con alcances contra esa misma URL falla silenciosamente, devolviendo respuestas que parecen anónimas. Debe llamar a https://api.atlassian.com/ex/jira/{cloudId} en su lugar.

No necesitas saber qué tipo tienes. Al inicio, el servidor sondea la URL del sitio con GET /rest/api/3/myself; si eso no devuelve una cuenta real, obtiene tu cloud ID de {site}/_edge/tenant_info y reintenta contra api.atlassian.com. El ganador se almacena en caché durante la vida del proceso y se registra en stderr.

Si la detección falla alguna vez: _edge/tenant_info no es parte de la API REST formalmente soportada de Atlassian (aunque los documentos de soporte de Atlassian la señalan), por lo que podría cambiar. En ese caso, establece ATLASSIAN_CLOUD_ID en .env para omitir la detección; el mensaje de error te dirá cuándo aplica. Casi nunca lo necesitas.

Configuración de PyCharm

1. Intérprete: Settings → Project → Python Interpreter → Add Interpreter → Existing → selecciona .venv/bin/python en el directorio del proyecto. (Si ejecutaste uv sync, el venv ya existe con todo instalado.)

2. Configuración de ejecución para depuración: Run → Edit Configurations → + → Python:

   • Run: módulo jira_mcp (elige "module" en lugar de "script path")

   • Parameters: --check PROJ-123

   • Working directory: la raíz del proyecto (cualquier cosa funciona, pero esto es ordenado)

   Ahora puedes establecer puntos de interrupción en cualquier lugar (p. ej. en client.py) y depurar solicitudes reales. Los errores dentro de un servidor MCP en ejecución son invisibles de otro modo.

Conectar a Claude Code

Usa el Python del venv por ruta absoluta; un python simple no se resolverá al venv cuando Claude Code inicie el servidor.

macOS/Linux:

claude mcp add jira -- /path/to/PythonProject/.venv/bin/python -m jira_mcp

Windows:

claude mcp add jira -- C:\path\to\PythonProject\.venv\Scripts\python.exe -m jira_mcp

Notas:

• Todo lo que está después de -- es el comando que Claude ejecuta; todo lo que está antes son las propias opciones de Claude.

• El alcance predeterminado es local (solo tú, solo este proyecto, almacenado en ~/.claude.json). Agrega --scope project para compartir mediante un .mcp.json verificado, o --scope user para usarlo en todos tus proyectos.

Verificar que está conectado

Dentro de una sesión de Claude Code:

• Ejecuta /mcp; el servidor jira debería aparecer como conectado, con seis herramientas.

• O simplemente pregunta: "usa whoami para verificar la conexión de jira".

Solución de problemas

Notas para desarrolladores nuevos en Python

• El venv (.venv/) es una copia local del proyecto de Python más los paquetes de este proyecto: el equivalente de node_modules, excepto que el intérprete mismo también vive dentro. Por eso Claude Code debe recibir .venv/bin/python por ruta absoluta: no hay una instalación global a la que recurrir.

• asyncio.run(...) es necesario porque las funciones asíncronas en Python no se ejecutan solo con llamarlas; llamar a una devuelve un objeto coroutine, y algo tiene que impulsarlo. No hay un bucle de eventos ambiental como en Node; asyncio.run() crea un bucle, ejecuta una coroutine hasta completarla y desarma el bucle. El servidor MCP hace esto internamente mediante mcp.run(); el modo --check lo hace explícitamente.

• Los decoradores (@mcp.tool) son funciones que reciben la función definida debajo de ellos y la registran/envuelven, como una fábrica de middleware aplicada en el momento de la definición. El decorador de FastMCP lee el nombre, las sugerencias de tipo y el docstring de la función para generar el esquema de herramienta MCP que Claude ve; el docstring es la documentación de la API de la herramienta.

• python -m jira_mcp ejecuta el __main__.py del paquete, lo más parecido que Python tiene a una entrada bin de npm. Funciona desde cualquier directorio porque uv sync instaló el proyecto en el venv.