Jira

MCP

Integrate Atlassian Jira for issue tracking, project management, and workflow automation in your Devgraph knowledge graph.

Overview

The Jira molecule connects to Atlassian Jira to manage issues, projects, and workflows. It provides MCP tools for creating, updating, and searching issues, plus entity synchronization to your knowledge graph.

Key Features:

• Create, update, and search Jira issues
• Discover projects and issues automatically
• Link issues to projects and other entities
• Support for both Jira Cloud and Server/Data Center
• JQL (Jira Query Language) search support
• Issue transitions and comment management

Quick Start

providers:
  - name: jira
    type: jira
    every: 300
    config:
      namespace: default
      base_url: https://your-company.atlassian.net
      email: ${JIRA_EMAIL}
      api_token: ${JIRA_API_TOKEN}
      cloud: true
      selectors:
        - project_keys: ["PROJ", "DEV"]

Configuration

Jira Cloud Configuration (Recommended)

providers:
  - name: jira-cloud
    type: jira
    every: 300
    config:
      namespace: default
      base_url: https://your-company.atlassian.net
      email: your-email@company.com
      api_token: ${JIRA_API_TOKEN}
      cloud: true
      selectors:
        - project_keys: ["PROJ", "DEV", "OPS"]
          include_archived: false

Jira Server/Data Center Configuration

providers:
  - name: jira-server
    type: jira
    every: 300
    config:
      namespace: default
      base_url: https://jira.company.com
      username: ${JIRA_USERNAME}
      password: ${JIRA_PASSWORD}
      cloud: false
      selectors:
        - project_keys: ["PROJ"]

Configuration Options

Option	Type	Required	Default	Description
namespace	string	No	default	Namespace for created entities
base_url	string	Yes	-	Jira instance URL
email	string	Yes*	-	Email for Jira Cloud authentication
api_token	string	Yes*	-	API token for Jira Cloud
username	string	Yes**	-	Username for Server/Data Center
password	string	Yes**	-	Password for Server/Data Center
cloud	boolean	No	true	Whether this is Jira Cloud
selectors	list	No	[]	Project selection criteria

*Required for Jira Cloud **Required for Jira Server/Data Center

Selector Options

Each selector specifies which projects to discover:

Option	Type	Required	Default	Description
project_keys	list	No	[]	List of project keys to include
jql_filter	string	No	-	JQL query to filter issues
include_archived	boolean	No	false	Include archived projects

Authentication

Jira Cloud (API Token)

Rate Limit: 10,000 requests/hour per user

1. Go to Atlassian API Tokens
2. Click "Create API token"
3. Give it a label (e.g., "Devgraph Integration")
4. Copy the token
5. Configure:

email: your-email@company.com
api_token: ${JIRA_API_TOKEN}
cloud: true

Set environment variable:

export JIRA_EMAIL="your-email@company.com"
export JIRA_API_TOKEN="your-api-token-here"

Jira Server/Data Center

Use your regular username and password:

username: ${JIRA_USERNAME}
password: ${JIRA_PASSWORD}
cloud: false

Set environment variables:

export JIRA_USERNAME="your-username"
export JIRA_PASSWORD="your-password"

MCP Tools

The Jira molecule provides the following MCP tools:

Issue Management

jira_create_issue

Create a new Jira issue.

jira_create_issue(
    project="PROJ",
    summary="Implement new authentication system",
    issue_type="Task",
    description="Detailed description of the task",
    assignee="john.doe",
    labels=["backend", "security"],
    priority="High"
)

Parameters:

• project (required): Project key
• summary (required): Issue title
• issue_type (required): Task, Bug, Story, Epic, etc.
• description: Detailed description
• assignee: Username to assign
• labels: List of labels
• priority: Priority level

jira_get_issue

Get details of a specific issue.

jira_get_issue(issue_key="PROJ-123")

jira_update_issue

Update an existing issue.

jira_update_issue(
    issue_key="PROJ-123",
    summary="Updated title",
    description="Updated description",
    assignee="jane.doe"
)

jira_search_issues

Search issues using JQL (Jira Query Language).

jira_search_issues(
    jql="project = PROJ AND status = 'In Progress'",
    max_results=50
)

jira_add_comment

Add a comment to an issue.

jira_add_comment(
    issue_key="PROJ-123",
    comment="This is a comment"
)

jira_transition_issue

Transition an issue to a different status.

jira_transition_issue(
    issue_key="PROJ-123",
    transition="Done",
    comment="Completed the task"
)

Project Management

jira_get_project

Get details of a specific project.

jira_get_project(project_key="PROJ")

jira_list_projects

List all accessible projects.

jira_list_projects()

Entities Created

JiraIssue

Represents a work item in Jira.

Entity Structure:

apiVersion: entities.devgraph.ai/v1
kind: JiraIssue
metadata:
  name: proj-123
  namespace: default
  labels:
    project: PROJ
    issue_type: Task
    status: In Progress
spec:
  key: PROJ-123
  project_key: PROJ
  summary: Implement authentication
  issue_type: Task
  status: In Progress
  assignee: john.doe
  reporter: jane.doe
  priority: High
  labels:
    - backend
    - security
  created: "2024-01-15T10:00:00Z"
  updated: "2024-01-16T14:30:00Z"

Key Fields:

• key: Issue key (e.g., "PROJ-123")
• project_key: Project the issue belongs to
• summary: Issue title
• issue_type: Task, Bug, Story, Epic, Subtask
• status: Current workflow status
• assignee: Assigned user
• reporter: User who created the issue
• priority: Priority level

JiraProject

Represents a Jira project containing issues.

Entity Structure:

apiVersion: entities.devgraph.ai/v1
kind: JiraProject
metadata:
  name: proj
  namespace: default
  labels:
    project_type: software
spec:
  key: PROJ
  name: My Project
  description: Project description
  lead: project.lead
  project_type: software

Key Fields:

• key: Project key (e.g., "PROJ")
• name: Project name
• description: Project description
• lead: Project lead username
• project_type: Type of project (software, business, etc.)

Relationships

IN_PROJECT

Issues belong to projects.

JiraIssue --IN_PROJECT--> JiraProject

Example:

PROJ-123 --IN_PROJECT--> PROJ

ASSIGNED_TO

Issues can be assigned to users (if user entities exist).

JiraIssue --ASSIGNED_TO--> User

BLOCKS

Issues can block other issues.

JiraIssue --BLOCKS--> JiraIssue

RELATED_TO

Issues can be related to other entities in the knowledge graph.

JiraIssue --RELATED_TO--> [Any Entity]

JQL Examples

Jira Query Language (JQL) is used to search for issues:

Find Open Bugs

project = PROJ AND type = Bug AND status = Open

Find Your Assigned Tasks

assignee = currentUser() AND status != Done

Find Recently Updated Issues

project = PROJ AND updated >= -7d

Find High Priority Issues

priority = High AND status in ("To Do", "In Progress")

Find Issues by Label

project = PROJ AND labels = backend

Find Issues Due This Week

project = PROJ AND due >= startOfWeek() AND due <= endOfWeek()

Complex Query

project = PROJ AND
  type in (Bug, Task) AND
  status = "In Progress" AND
  assignee in (currentUser(), "john.doe") AND
  updated >= -3d

Filtering Projects

Select Specific Projects

selectors:
  - project_keys: ["PROJ", "DEV", "OPS"]

Include Archived Projects

selectors:
  - project_keys: ["PROJ"]
    include_archived: true

Filter Issues with JQL

selectors:
  - project_keys: ["PROJ"]
    jql_filter: "labels = backend AND created >= -30d"

Use Cases

Multi-Project Discovery

selectors:
  - project_keys: ["BACKEND", "FRONTEND", "INFRA"]

Team-Specific Issues

selectors:
  - project_keys: ["PROJ"]
    jql_filter: "labels = platform-team"
  - project_keys: ["DEV"]
    jql_filter: "labels = product-team"

Environment Separation

# Production issues
- name: jira-prod
  config:
    namespace: production
    selectors:
      - project_keys: ["PROD"]

# Development issues
- name: jira-dev
  config:
    namespace: development
    selectors:
      - project_keys: ["DEV"]

Troubleshooting

Authentication Failed

Symptom: "401 Unauthorized" error

Solutions:

1. Verify email and API token are correct (Cloud)
2. Check username and password (Server/Data Center)
3. Ensure the base URL includes https://
4. For Cloud: Verify API token hasn't expired
5. Check user has access to the Jira instance

Permission Denied

Symptom: "403 Forbidden" error

Solutions:

1. Verify user has access to the specified projects
2. Check Jira permission scheme for the project
3. Ensure user has "Browse Projects" permission
4. For Server: Check user is in the correct groups

Project Not Found

Symptom: Project key not found

Solutions:

1. Verify project key is correct (case-sensitive)
2. Check user has access to the project
3. Ensure project is not archived (unless include_archived: true)
4. Check project exists in the Jira instance

Transition Not Found

Symptom: Transition name not valid

Solutions:

1. Use jira_get_issue to see available transitions
2. Transition names are case-sensitive
3. Transitions depend on current issue status
4. Check workflow configuration in Jira

Rate Limit Exceeded

Symptom: "429 Too Many Requests" error

Solutions:

1. Increase reconciliation interval (every: 600 for 10 minutes)
2. Reduce number of projects/issues being synced
3. Use JQL filters to limit issue discovery
4. For Cloud: Default limit is 10,000 requests/hour per user

Performance Tips

1. Use JQL filters: Filter issues at the API level instead of syncing everything
2. Limit project scope: Only sync projects you need
3. Adjust interval: Balance freshness vs. API usage
4. Exclude archived: Set include_archived: false to reduce API calls
5. Paginate carefully: Use reasonable max_results in searches

Integration Examples

Link Issues to GitHub Pull Requests

Use Jira issue keys in PR titles/descriptions:

[PROJ-123] Fix authentication bug

The system can automatically link:

JiraIssue (PROJ-123) --IMPLEMENTED_BY--> GithubPullRequest

Link Issues to Services

In your .devgraph.yaml:

relations:
  - source:
      kind: JiraIssue
      name: proj-123
    target:
      kind: Service
      name: auth-service
    relation: RELATES_TO

Link Issues to Deployments

Track which issues are deployed:

JiraIssue --DEPLOYED_IN--> ArgoApplication

Next Steps

• Configure GitHub molecule to link PRs to Jira issues
• Set up Grafana molecule to track dashboards mentioned in issues
• Learn about entity relationships