devflow-mcp

Local, read-only MCP server that securely serves Jira (Server/Data Center) data to Claude Code — without ever exposing your PAT/token to the model. (GitLab tools + the /devflow skill land in later phases; see the plan.)

Plan: plans/260625-1353-jira-ai-dev-mcp/

Why

The token lives only inside this server's HTTP client (read from an env var). Claude calls tools like jira_get_ticket_bundle("PROJ-123") and gets back trimmed JSON — it never sees the credential, and the credential is never a tool argument.

Requirements

• Python ≥ 3.10
• A Jira Server/DC Personal Access Token (Bearer). Profile → Personal Access Tokens.

Setup

cd devflow-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .            # or: pip install -e ".[dev]" for tests

cp .env.example .env        # then edit JIRA_BASE_URL + JIRA_PAT

.env (gitignored) for local runs:

JIRA_BASE_URL=https://jira.your-company.com
JIRA_PAT=xxxxxxxxxxxx

Smoke test (MCP Inspector)

fastmcp dev server.py
# open the Inspector URL, call jira_get_ticket_bundle with a real issue key

First, call jira_get_fields once and note the custom field IDs for Sprint / Epic Link / Story Points — needed in later phases.

Register in Claude Code

Add to your project .mcp.json (commit this — it has NO secrets, only ${VAR} refs):

{
  "mcpServers": {
    "devflow": {
      "command": "/ABS/PATH/devflow-mcp/.venv/bin/python",
      "args": ["/ABS/PATH/devflow-mcp/server.py"],
      "env": {
        "JIRA_BASE_URL": "${JIRA_BASE_URL}",
        "JIRA_PAT": "${JIRA_PAT}",
        "GITLAB_URL": "${GITLAB_URL}",
        "GITLAB_TOKEN": "${GITLAB_TOKEN}"
      }
    }
  }
}

Put the real values in your shell (~/.zshrc). GitLab is optional — omit it and GitLab tools self-disable:

export JIRA_BASE_URL="https://jira.your-company.com"
export JIRA_PAT="xxxxxxxxxxxx"
export GITLAB_URL="https://gitlab.your-company.com"   # self-hosted; /api/v4 appended automatically
export GITLAB_TOKEN="glpat-xxxxx"                       # scopes: read_api, read_repository

Restart Claude Code, then the tools appear.

Tools (21, all read-only)

Jira core

Tool	Purpose
jira_get_ticket_bundle(key)	primary: issue + subtasks + links + comments + attachment metadata in one call
jira_get_issue(key, fields?)	single issue, trimmed
jira_get_comments(key, limit?)	recent comments
jira_get_subtasks(key) / jira_get_linked_issues(key)	subtasks / linked issues
jira_search(jql, fields?, limit?)	JQL search (paginated, capped)
jira_get_fields()	resolve custom field IDs (setup)

Jira agile — jira_get_epic, jira_get_epic_issues, jira_get_sprint, jira_get_sprint_issues

Jira attachments (image analysis) — jira_get_attachments(key), jira_download_attachment(key, attachment_id) → downloads to a local path (token hidden) so Claude can read mockups/screenshots with vision.

GitLab (self-hosted, optional) — gitlab_search_mrs(ticket_key), gitlab_get_mr, gitlab_get_mr_commits, gitlab_get_commits, gitlab_get_commit_diff, gitlab_get_pipeline_status, gitlab_search_code, gitlab_get_file.

Security notes

• Secrets are read from env only; never accepted as args, never returned, masked in errors.
• Read-only: no write/transition/comment endpoints are implemented.
• JIRA_VERIFY_SSL=false only for trusted internal self-signed certs.

Troubleshooting

• Exits "Missing required environment variable" → set JIRA_BASE_URL / JIRA_PAT.
• 401/403 → check PAT validity + project permissions.
• SSL error on internal host → set JIRA_VERIFY_SSL=false (trusted hosts only).