TamarEngel/jira-github-mcp

Jira - GitHub MCP Server

A modular and extensible Model Context Protocol (MCP) server for Jira and
GitHub integration, enabling end-to-end automation of developer workflows -
from issue tracking to code changes and pull request management - via AI
agents inside the IDE.

Overview

• Jira integration: fetch issues by filters, search via JQL, and transition issues across workflows

• GitHub integration: create branches, open and merge PRs

• Local Git operations: stage, commit, and push changes locally

• IDE-native: works with any MCP-compatible agent (e.g., GitHub Copilot) over stdio

• End-to-end workflow: Jira issue → branch → code → commit → PR → merge → Jira status update

Why

Developers constantly context-switch between Jira, GitHub, and their IDE,
breaking focus and slowing down delivery. This project transforms that workflow
into a seamless, IDE-native, conversational experience, allowing developers to
move from Jira issue to merged pull request using natural language and
AI-assisted automation.

Features

• Retrieve, filter, and search Jira issues using fields and JQL

• Transition Jira issues across workflow statuses

• Automate branch creation as part of the Jira-driven workflow

• Commit and push changes from the local Git repository

• Create and merge GitHub pull requests

• MCP resources providing workflow guidance and current issue context

Available Tools

| Tool | Description |
|------|-------------|
| jira_get_issue | Retrieve a Jira issue by key (e.g., KAN-1) with configurable fields |
| jira_search_issues | Search Jira using JQL; paginate and filter results |
| jira_get_my_issues | List issues assigned to the current user, optionally filtered by status/type... |
| jira_transition_issue | Move an issue to another status with optional comment |
| create_branch_for_issue | Create a new Git branch (e.g., feature/KAN-15) based on a Jira issue |
| create_pull_request | Create a PR on GitHub from a branch |
| git_commit_and_push | Stage all changes, commit with a message, and push to a branch |
| merge_pull_request | Merge a PR using squash, merge, or rebase; optionally check CI status |

Project Structure

• src/ — Application source code

• tests/ — Integration and unit tests

• pyproject.toml — Project metadata and dependencies

• uv.lock — Dependency lockfile

Architecture Overview

High-level overview of the system design and main components.

See full architecture documentation: docs/architecture.md

Installation & Setup

Requirements

• Python 3.10+

• Git (available on PATH)

• Jira instance (Cloud or self-hosted) with REST API v3 access

• GitHub repository with token-based API access

1. Clone the Repository

git clone https://github.com/YOUR-USERNAME/jira-github-mcp.git
cd jira-github-mcp

2. Create & Activate a Virtual Environment

Using uv (recommended)

uv venv

Or with python

python -m venv .venv

3. Install Dependencies

Using uv (recommended):

uv sync

Or with pip:

pip install -r requirements.txt

The project depends on:

• fastmcp: MCP protocol and server utilities

4. Configure Environment Variables

Create a .env file in the repository root:

# Jira Configuration
JIRA_BASE_URL=https://your-instance.atlassian.net
[email protected]
JIRA_API_TOKEN=your-jira-api-token

GitHub Configuration
GITHUB_TOKEN=your-github-personal-access-token
GIT_REPO_URL=https://github.com/owner/repo.git
GIT_DEFAULT_BRANCH=main
Optional: Local Git Repository Path
If omitted, defaults to the current working directory
GIT_REPO_LOCAL_PATH=/path/to/local/repo

Notes:

• JIRA_BASE_URL should not end with /

• Grant the GitHub PAT only the minimal permissions required (branches, pull requests, etc.)

5. Run the MCP Server

Run the server as a Python module:

python -m src.server.server

If you defined an entrypoint, you can also run:

mcp-server

6. Connect from an MCP Client

To use this server with an MCP client (e.g., VS Code / GitHub Copilot), configure the client to run the server from the project root.

Example MCP configuration:

{
  "servers": {
    "jira-github-mcp-server": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "src.server.server"],
      "cwd": "/absolute/path/to/jira-github-mcp"
    }
  }
}

> Note: Replace /absolute/path/to/mcp-server with the actual path to the repository.

Connecting to GitHub Copilot

Here's how to connect and start using the server with Copilot:

1. Open VS Code and ensure GitHub Copilot is installed
2. Sign in with your GitHub account (if not already signed in)
3. Add the MCP server configuration to your VS Code settings (see JSON above)
4. Reload VS Code
5. Start asking Copilot natural language questions—it will invoke the tools automatically

How It Works

%%{init: {'flowchart': {'htmlLabels': true, 'useMaxWidth': false, 'fontSize': 12}}}%%
graph LR
    IDE["Your IDE<br/>VS Code + Copilot"]
    MCP["MCP Server"]
    JIRA["Jira API<br/>(httpx.Async)"]
    GITHUB["GitHub API<br/>(httpx.Async)"]
    GIT["Local Git"]
    
    IDE -->|ask| MCP
    MCP -->|fetch/update| JIRA
    MCP -->|create/merge| GITHUB
    MCP -->|commit/push| GIT
    MCP -->|respond| IDE

Example Workflow

This example demonstrates a complete issue-to-merge flow using GitHub Copilot with this MCP server.

1. Discover the next task

Ask Copilot:
> "What is the most urgent task assigned to me?"

Call Tools:
- jira_get_my_issues — list issues assigned to the user
- jira_search_issues — prioritize by status or urgency

_Selected issue: KAN-42_

2. Start working on the issue

Ask Copilot:
> "Start work on KAN-42"

Call Tools:
- jira_get_issue(issue_key="KAN-42")
- create_branch_for_issue(issue_key="KAN-42")
- jira_transition_issue(issue_key="KAN-42", to_status="In Progress")

Make changes in your editor.

3. Commit changes

Ask Copilot:
> "Commit my changes with message 'Implement KAN-42'"

Call Tools:
- git_commit_and_push(message="Implement KAN-42", branch="feature/KAN-42")

4. Create a pull request

Ask Copilot:
> "Create a PR for KAN-42"

Call Tools:
- create_pull_request(issue_key="KAN-42", branch_name="feature/KAN-42")
- jira_transition_issue(issue_key="KAN-42", to_status="In Review")

Code review and CI checks run on GitHub.

5. Merge and close the issue

Ask Copilot:
> "Merge the PR and move KAN-42 to Done"

Call Tools:
- merge_pull_request(pr_number=123)
- jira_transition_issue(issue_key="KAN-42", to_status="Done")

Issue closed, code merged, workflow complete.

Use Cases

• Day-to-day development workflows across Jira issues, branches, and pull requests

• Code review processes with clear pull request status tracking

• Sprint execution and task progress visibility

• Rapid bug fixes and hotfix workflows

• End-to-end feature development from issue to merge

• Team collaboration with consistent status and ownership tracking

Future Enhancements

• Multi-platform support: Extend integrations beyond GitHub to additional platforms (e.g. GitLab)

• Smarter workflows: Multi-repo support, reusable JQL templates, and configurable automation rules

• Deeper automation: AI-assisted PR/commit drafting, webhook-driven synchronization, and CI/CD feedback

Summary

This MCP server provides a clear and traceable development workflow by connecting Jira and GitHub through a single conversational interface.

By reducing manual coordination and keeping issues, branches, and pull requests in sync, it helps teams focus on development rather than process.

*Designed with a focus on clarity, extensibility, and developer experience.*