mcp-server-r4j 0.1.0

MCP server for R4J (Requirements for Jira) — manage folders, issues, and tree structure in Jira Data Center

R4J Data Center MCP Server

MCP server for R4J (Requirements for Jira) — Data Center / Server only. Manage the R4J folder tree, add/move/remove issues, and query the hierarchy. Uses the official R4J REST API 1.0.

Jira Cloud is not supported. The R4J Cloud product exposes a different API shape; this server targets Data Center / Server endpoints only.

Tools

Tool	Description
r4j_healthcheck	Validate connectivity, auth, license, and (optionally) a project key
r4j_get_tree	Get tree structure (folders + issues) for a project or folder
r4j_get_folders	Get all folders for a project
r4j_get_folder_context	Get folder metadata, child folders, and issues in one call
r4j_create_folder	Create a folder (at root or under a parent)
r4j_ensure_folder_path	Resolve or create a folder path (idempotent)
r4j_rename_folder	Rename a folder
r4j_delete_folder	Delete a folder (cascades to descendants)
r4j_move_folder	Move a folder to another folder (requires R4J 4.2.2+)
r4j_add_issue	Add a Jira issue to a folder (idempotent)
r4j_remove_issue	Remove an issue from the tree (not from Jira)
r4j_move_issue	Move an issue between folders

Compatibility

Verified against:

• Jira Data Center 10.3.13 (Atlassian Jira Project Management Software)
• R4J (easeRequirements Data Center) 5.3.1-10-jira10

Other Jira DC / Server and R4J versions are likely to work but are not tested. r4j_move_folder requires R4J 4.2.2+.

Installation

With uvx (recommended)

uvx mcp-server-r4j

Or from a local checkout:

uvx --from /path/to/mcp-server-r4j mcp-server-r4j

With pip

pip install mcp-server-r4j
mcp-server-r4j

Configuration

Set these environment variables before starting the server. The server fails fast at startup if required vars are missing or malformed.

Variable	Required	Default	Description
R4J_JIRA_URL	yes	—	Base Jira URL, e.g. https://jira.example.com/jira. Must start with http:// or https://.
R4J_JIRA_PAT	yes	—	Jira Personal Access Token (Bearer).
R4J_PROJECT_KEY	no	—	Default project key (e.g. PROJ). Used when a tool call omits project_key.
R4J_TIMEOUT_SECONDS	no	30	HTTP timeout for API calls (must be > 0).
R4J_VERIFY_SSL	no	true	Set to false to disable TLS verification (lab / self-signed setups only).
R4J_CA_BUNDLE	no	—	Path to a custom CA bundle. Overrides R4J_VERIFY_SSL when set.
R4J_DEBUG	no	false	If true, tool errors include full upstream response bodies. Off by default to avoid leaking internal hostnames / HTML error pages to the LLM.

export R4J_JIRA_URL="https://jira.example.com/jira"
export R4J_JIRA_PAT="your-personal-access-token"
export R4J_PROJECT_KEY="PROJ"  # optional default

After starting the server, call r4j_healthcheck first to verify auth, R4J license, and project reachability.

Claude Desktop Setup

Edit %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/.config/claude/claude_desktop_config.json (Linux):

{
  "mcpServers": {
    "r4j": {
      "command": "uvx",
      "args": ["mcp-server-r4j"],
      "env": {
        "R4J_JIRA_URL": "https://jira.example.com/jira",
        "R4J_JIRA_PAT": "your-pat-here",
        "R4J_PROJECT_KEY": "PROJ"
      }
    }
  }
}

For a local checkout (not yet published to PyPI):

{
  "mcpServers": {
    "r4j": {
      "command": "uvx",
      "args": ["--from", "/path/to/mcp-server-r4j", "mcp-server-r4j"],
      "env": {
        "R4J_JIRA_URL": "https://jira.example.com/jira",
        "R4J_JIRA_PAT": "your-pat-here",
        "R4J_PROJECT_KEY": "PROJ"
      }
    }
  }
}

Windows + WSL

{
  "mcpServers": {
    "r4j": {
      "command": "wsl",
      "args": ["uvx", "--from", "/path/to/mcp-server-r4j", "mcp-server-r4j"],
      "env": {
        "R4J_JIRA_URL": "https://jira.example.com/jira",
        "R4J_JIRA_PAT": "your-pat-here",
        "R4J_PROJECT_KEY": "PROJ"
      }
    }
  }
}

Claude Code Setup

# From PyPI (once published):
claude mcp add r4j -- uvx mcp-server-r4j

# From local checkout:
claude mcp add r4j -- uvx --from /path/to/mcp-server-r4j mcp-server-r4j

To pass env vars so they persist in the Claude Code config:

claude mcp add r4j \
  -e R4J_JIRA_URL=https://jira.example.com/jira \
  -e R4J_JIRA_PAT=your-pat-here \
  -e R4J_PROJECT_KEY=PROJ \
  -- uvx --from /path/to/mcp-server-r4j mcp-server-r4j

Example Workflows

Create a folder and add issues:

1. r4j_ensure_folder_path → path="Sprint 42"
2. r4j_add_issue → issue_key="PROJ-123", folder_path="Sprint 42"

Move an issue between folders:

• r4j_move_issue → issue_key="PROJ-123", from_folder_path="Sprint 42", to_folder_path="Sprint 43"

Browse folder structure:

1. r4j_get_folder_context → folder_path="Sprint 42" (structured: child folders, issues, counts)
2. r4j_get_tree → folder_path="Sprint 42" (raw tree for deeper inspection)