Enterprise Issue Tracking Nexus (JIRA Connector)

This Model Context Protocol (MCP) establishes a robust interface for interacting with Atlassian JIRA services via the Claude Desktop environment.

Core Capabilities

• Execute complex data retrieval against JIRA issues utilizing JQL (JIRA Query Language).
• Enumerate available JIRA project spaces accessible to the authenticated principal.
• Programmatic lifecycle management for JIRA entities: instantiation, revision, and destruction.
• Ability to append commentary and orchestrate status advancements for tracked tickets.
• Secure user lookups, featuring built-in mechanisms to uphold data privacy mandates.

Setup Procedure

1. Obtain the source code repository: bash git clone https://github.com/yourusername/mcp-jira.git cd mcp-jira

2. Establish and activate a dedicated isolated Python environment: ```bash # Unix-like systems python -m venv venv source venv/bin/activate

# Windows environment python -m venv venv .\venv\Scripts\activate ```

1. Install required software dependencies: bash pip install -r requirements.txt

2. Generate and populate the configuration file (.env) within the primary directory: bash touch .env

3. Input your JIRA access credentials into .env: JIRA_SERVER=https://your-domain.atlassian.net JIRA_EMAIL=your.email@example.com JIRA_API_TOKEN=your_api_token_here

4. Validation of the setup: ```bash # Execute the complete test suite python -m pytest

# Run specific validation routine python -m pytest tests/test_search_issues.py ```

1. Initiate the MCP operational service: bash python run.py

Credential Provisioning (API Token)

Authentication against your JIRA deployment requires a dedicated API Access Key:

1. Access your Atlassian profile management dashboard.
2. Navigate to Security settings, specifically the API token creation interface.
3. Select "Generate New API Token".
4. Assign a descriptive label (e.g., "Claude Integration Access").
5. Securely store the resultant token immediately upon generation.

Privacy Safeguards (GDPR Adherence)

If operating against a JIRA Cloud tenancy configured for stringent GDPR protocols:

1. Identity resolution searches will strictly resolve based on user display names and associated electronic mail addresses.
2. Queries targeting immutable user identifiers (usernames) are unsupported.
3. The volume and detail of returned data may be constrained by prevailing access permissions.
4. The utility autonomously adapts API calls for compliance, though users may need to refine query terms.

Known Operational Hurdles & Fixes

1. Missing Library Reference ('src') bash # Invoke script ensuring correct path context PYTHONPATH=/path/to/mcp-jira python run.py

2. Authentication Failure on API Call

3. Verify token integrity.
4. Confirm the configured email matches the token's owning Atlassian account.

5. Validate the base URL for the JIRA instance is precise (must include https://).

6. Errors Related to Data Sovereignty

7. If errors mention "username parameter unsupported," your instance enforces GDPR restrictions.
8. Substitute usernames with display names or full email addresses in queries.
9. The tool is engineered to compensate for these constraints automatically.

Toolset Documentation

Item Retrieval

Locate JIRA entities using JQL.

Inputs: - jql: JQL predicate (e.g., "project=ALPHA AND priority='Highest'") - max_results: Pagination limit (default: 10) - fields: Desired data fields, delimited by commas (default: "summary,status,assignee")

Item Fabrication

Introduce a novel JIRA artifact.

Inputs: - project_key: Target project identifier (e.g., "ALPHA") - summary: Concise title for the artifact - description: Detailed textual context (optional) - issue_type: Classification (default: "Task"; options include "Bug", "Story", etc.) - priority: Severity designation (optional) - assignee: Target user ID for assignment (optional)

Item Revision

Modify parameters of an existing JIRA entry.

Inputs: - issue_key: Unique identifier (e.g., "ALPHA-456") - summary, description, status, priority, assignee: Optional fields for modification. - comment: Text to append during the update operation (optional)

Item Disposition

Permanently eliminate a JIRA artifact (requires explicit consent).

Inputs: - issue_key: Unique identifier (e.g., "ALPHA-456") - confirm: Mandatory flag, must be set to True to proceed.

Project Enumeration

Retrieve a manifest of accessible project spaces.

Inputs: - limit: Cap on the number of results returned (default: 10)

Comment Augmentation

Append a new observation to a specific ticket.

Inputs: - issue_key: Target artifact identifier. - comment: The textual content to be added.

Status Advancement

Move an artifact through its defined workflow states.

Inputs: - issue_key: Target artifact identifier. - status: The intended destination state (e.g., "Resolved", "Verified"). - comment: Optional contextual note for the transition.

Detail Retrieval

Fetch the complete data payload for a specific JIRA item.

Inputs: - issue_key: Unique identifier. - include_comments: Boolean flag to include associated discussion threads (default: False)

Identity Search

Locate registered JIRA personnel by various identifiers. Crucial for assignment or notification workflows.

Crucial Notice: For Cloud instances enforcing GDPR adherence (standard configuration), searches must utilize the generalized query field, targeting accessible public identifiers rather than direct usernames. The tool manages this translation internally.

Parameters: - query (str): The search string used for matching against visible names and email addresses. - Compliance Note: Searches map to display names and emails in privacy-locked environments. - Matching is always case-insensitive and supports substrings. - Example: Supplying "david" yields results matching "David Smith" or "david.w@corp.com" - max_results (int, optional): Upper boundary for returned identities (default: 10). - include_active_users (bool, optional): Flag to include currently operational accounts (default: True). - include_inactive_users (bool, optional): Flag to include archived/suspended accounts (default: False).

Example invocation for finding personnel:

# Seek users associated with 'support' in their visibility data
search_users(query="support")

# Extended search for up to 50 results, including deactivated personnel
search_users(
    query="alexander",
    max_results=50,
    include_inactive_users=True
)

Illustrative Operational Scenarios

Query for high-priority defects within the ALPHA space:
search_issues(jql="project=ALPHA AND issuetype=Bug AND priority='High'")

Instantiate a new failure report in ALPHA:
create_issue(project_key="ALPHA", summary="Critical: Login endpoint failing under load", description="POST /auth fails with 500 error", issue_type="Bug", priority="Highest")

Modify the title and advance ticket ALPHA-123 to 'Review':
update_issue(issue_key="ALPHA-123", summary="Resolved: Auth Failure on Load Test", status="In Review", comment="Team review requested.")

Permanently remove ticket ALPHA-123:
delete_issue(issue_key="ALPHA-123", confirm=True)

Fetch the initial 3 registered organizational spaces:
list_projects(limit=3)

Annotate ticket ALPHA-123 with an update from QA:
add_comment(issue_key="ALPHA-123", comment="QA verified the fix. Moving to Done.")

Advance ticket ALPHA-123 to final completion:
transition_issue(issue_key="ALPHA-123", status="Done", comment="Deployment complete.")

Examine ticket ALPHA-123 including all associated discussions:
get_issue_details(issue_key="ALPHA-123", include_comments=True)

Developer Information

Guidance for extending or modifying this software module:

1. Clone the repository.
2. Configure the isolated environment: python -m venv venv && source venv/bin/activate
3. Install dependencies: pip install -r requirements.txt
4. Execute regression tests: python -m pytest
5. Implement necessary modifications.
6. Validate functionality within the Claude Desktop execution context.