Skip to main content
Glama
Sign In
deenesjakoruzh
jira-mcp

jira-mcp

by vaspap1790
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Jira MCP サーバー

Jiraと連携するためのツールを提供するModel Context Protocol (MCP) サーバーです。Cursorやその他のMCPクライアントが、チケットの取得、リンクされたチケットの管理、チケットステータスの更新を行えるようにします。

クイックスタート

1. 依存関係のインストール

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install project dependencies
uv sync

2. Jira認証情報の設定

推奨: パーソナルアクセストークン (PAT)

  1. Jiraにログイン: https://jira.telekom.de

  2. プロフィール > パーソナルアクセストークン に移動

  3. 「トークンを作成」をクリック

  4. 名前（例: "Cursor MCP"）を付け、有効期限を設定

  5. 重要: トークンに 「読み取り」 または 「プロジェクトの閲覧」 権限があることを確認してください

  6. トークンをすぐにコピーしてください（二度と表示されません）

.env ファイルを作成:

cp .env.example .env

.env を編集して認証情報を入力:

JIRA_URL=https://jira.telekom.de
JIRA_USERNAME=your.username@telekom.de
JIRA_API_TOKEN=your_personal_access_token_here
JIRA_AUTH_TYPE=bearer

注意: Kantega SSO APIトークンにはIP制限がある場合や、管理者が設定した権限が必要な場合があります。ほとんどのユーザーにはパーソナルアクセストークンが推奨されます。

3. Cursorでの設定

  1. Cursorを開く

  2. Settings > Tools and MCP に移動

  3. 以下の設定を追加:

{
  "mcpServers": {
    "jira": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/jira-mcp",
        "run",
        "-m",
        "src"
      ]
    }
  }
}

重要: パスと認証情報は実際の値に置き換えてください！

  1. Cursorを完全に再起動

4. 試してみる

Cursorのチャットで以下を試してください:

  • "Get details for Jira ticket PROJ-123"

  • "Show me all linked tickets for PROJ-456"

  • "Update PROJ-789 status to In Progress"

Related MCP server: JIRA MCP Server

機能

利用可能なツール

ツール

説明

例

get_ticket

チケットの詳細を取得

"Get PROJ-123"

get_linked_tickets

関連チケットとサブタスクを取得

"Show linked tickets for PROJ-123"

update_ticket_status

チケットのステータスを更新

"Move PROJ-123 to In Progress"

認証サポート

  • Bearerトークン: パーソナルアクセストークン (PAT) - 推奨

  • 基本認証: ユーザー名 + APIトークン (Atlassian Cloud)

  • Cookie認証: セッションベースの認証 (フォールバックオプション)

ツールの詳細

get_ticket

チケットの完全な情報を取得します。

パラメータ:

  • ticket_id (string, 必須): チケットIDまたはキー (例: "PROJ-123")

戻り値:

{
  "key": "PROJ-123",
  "summary": "Ticket summary",
  "description": "Detailed description",
  "status": "In Progress",
  "issue_type": "Story",
  "priority": "High",
  "assignee": "John Doe",
  "reporter": "Jane Smith",
  "created": "2024-01-15T10:30:00.000+0000",
  "updated": "2024-01-20T14:45:00.000+0000",
  "comments_count": 3,
  "comments": [...],
  "custom_fields": {...}
}

get_linked_tickets

関連するすべてのチケットとサブタスクを取得します。

パラメータ:

  • ticket_id (string, 必須): チケットIDまたはキー

戻り値:

{
  "ticket": "PROJ-123",
  "linked_tickets": [
    {
      "link_type": "Blocks",
      "direction": "blocks",
      "key": "PROJ-124",
      "summary": "Related ticket",
      "status": "To Do"
    }
  ],
  "linked_tickets_count": 1,
  "subtasks": [...],
  "subtasks_count": 2
}

update_ticket_status

ワークフローの検証を行いながらチケットのステータスを更新します。

パラメータ:

  • ticket_id (string, 必須): チケットIDまたはキー

  • status (string, 必須): ターゲットステータス (例: "In Progress", "Done")

戻り値:

Successfully updated ticket PROJ-123 status from 'To Do' to 'In Progress'

注意: このツールは遷移を検証します。無効な場合は、利用可能な遷移を返します。

テスト

テストの実行

# Run all tests
.venv/bin/pytest tests/ -v

# Run with coverage
.venv/bin/pytest tests/ --cov=src -v

# Run specific test file
.venv/bin/pytest tests/test_integration/test_real_tickets.py -v

手動テスト

サーバーを直接テスト:

uv run --env-file .env -m src

Ctrl+Cを押して停止します。

トラブルシューティング

認証エラー

症状: "401 Unauthorized" または "403 Forbidden"

解決策:

  • 最も一般的: パーソナルアクセストークンの有効期限切れ - 新しいものを生成してください

  • PATに「読み取り」または「プロジェクトの閲覧」権限があることを確認

  • ユーザー名がJiraアカウントのメールアドレスと一致していることを確認

  • JIRA_URL に https:// が含まれていることを確認

  • パーソナルアクセストークンの場合、JIRA_AUTH_TYPE=bearer であることを確認

チケットが見つからない

症状: "404 Not Found"

解決策:

  • チケットキーが正しいか確認 (例: "PROJ-123")

  • チケットを表示する権限があるか確認

  • 正しいJiraインスタンスを使用しているか確認

Cursorにサーバーが表示されない

解決策:

  • MCP設定の絶対パスを確認

  • Python 3.12+ がインストールされているか確認: python3 --version

  • Cursorを完全に再起動 (終了して再度開く)

  • Cursorの開発者コンソールでエラーを確認

チケットを遷移できない

症状: "Invalid status transition"

解決策:

  • エラーメッセージに利用可能な遷移がリストされます

  • ステータス名は正確に一致する必要があります (大文字小文字を区別)

  • Jiraのワークフロー権限を確認

  • ワークフローに対して遷移が有効であることを確認

アーキテクチャ

このプロジェクトはSOLID原則とクリーンアーキテクチャに従っています:

src/
├── __init__.py
├── __main__.py           # Entry point
├── server.py             # MCP server setup
├── config/               # Configuration management
├── client/               # Jira API client
├── tools/                # 3 MCP tools
├── models/               # Domain models
├── mappers/              # Data transformation
└── utils/                # Error handling, JSON utils

主要原則:

  • SOLID: 単一責任、依存性逆転

  • DRY: 重複なし、再利用可能なコンポーネント

  • 型安全性: 全体を通して完全な型ヒント

  • テスト容易性: 関心の明確な分離

詳細な技術ドキュメントについては ARCHITECTURE.md を参照してください。

開発

プロジェクト構造

jira-mcp/
├── src/                  # Source code (22 Python files)
├── tests/                # Test suite
├── pyproject.toml        # Project config (includes pytest config)
├── .env.example          # Config template
├── .gitignore
├── README.md             # This file
└── ARCHITECTURE.md       # Technical docs

依存関係の追加

uv add package-name

異なる設定での実行

uv run --env-file .env.production -m src

コード品質

  • Lintエラー: 0

  • 型カバレッジ: 100%

  • テストカバレッジ: 3つのツールすべてに対する統合テスト

  • アーキテクチャ: SOLID + DRY準拠

要件

  • Python 3.12+

  • APIアクセス権を持つJiraアカウント

  • Jira APIトークン (Kantega SSO Enterprise または Atlassian Cloud)

ライセンス

このプロジェクトは、CursorおよびJiraで使用するために現状のまま提供されます。

SOLIDおよびDRY原則に従ったベストプラクティスで構築されています 🚀

Available Tools

3 tools
get_linked_ticketsA

Fetch all linked tickets and subtasks for a given Jira ticket. Returns issue links (blocks, is blocked by, relates to, etc.) and subtasks with their summaries and statuses.

NameRequiredDescriptionDefault
ticket_idYesThe Jira ticket ID or key (e.g., 'PROJ-123')

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It discloses what is returned (issue links and subtasks with summaries and statuses) but lacks details on authorization, pagination, or limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose followed by output details. No redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given one required parameter and no output schema, the description covers purpose, parameter, and return structure. It lacks error handling or clarification on depth of links, but is relatively complete for a simple fetch tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema coverage is 100% with a description of ticket_id. The description adds an example format ('e.g., 'PROJ-123'') but does not provide additional semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Fetch' and the resource 'all linked tickets and subtasks for a given Jira ticket', distinguishing it from siblings like get_ticket which returns a single ticket.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when needing linked tickets or subtasks, but does not explicitly state when to use this tool versus alternatives like get_ticket or update_ticket_status.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_ticketA

Fetch full details of a Jira ticket by its ID or key. Returns comprehensive ticket information including summary, description, status, issue type, priority, assignee, reporter, comments, and custom fields.

NameRequiredDescriptionDefault
ticket_idYesThe Jira ticket ID or key (e.g., 'PROJ-123')

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. Description discloses that the tool fetches (read operation) and lists returned fields, but does not mention rate limits, required permissions, error cases, or side effects. It adds value over schema by specifying return contents but lacks full behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first states action and input, second lists outputs. No extraneous words, front-loaded, and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with no output schema, the description provides a good overview of return content (summary, description, status, etc.). Minor gap: custom fields are vague and exact structure not detailed, but sufficient for basic understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a description for ticket_id. The description reiterates 'by its ID or key' without adding new meaning beyond the schema's example. Hence, baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it fetches full details of a Jira ticket by ID or key and lists returned information (summary, status, etc.). It distinguishes from sibling tools ('get_linked_tickets', 'update_ticket_status') implicitly by resource and verb, but does not explicitly contrast them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use (when you need ticket details) but does not explicitly state when not to use or suggest alternatives like get_linked_tickets for linked issues.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_ticket_statusA

Update the status of a Jira ticket by transitioning it to a new status. Validates that the transition is valid for the ticket's current workflow. Common statuses include: 'To Do', 'In Progress', 'In Review', 'Done'.

NameRequiredDescriptionDefault
ticket_idYesThe Jira ticket ID or key (e.g., 'PROJ-123')
statusYesThe target status name (e.g., 'In Progress', 'Done')

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden. It mentions validation of transitions, but does not disclose side effects (e.g., notifications), permissions requirements, idempotency, or error handling behavior. This is adequate but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the action, and contains no redundant information. Every sentence contributes meaningful context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 params, no nested objects), the description is mostly complete. However, it omits the return value or success/error behavior, which would be helpful since there is no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, earning a baseline of 3. The description adds value by listing common statuses ('To Do', 'In Progress', 'In Review', 'Done'), which provides context beyond the schema's generic description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Update the status of a Jira ticket by transitioning it to a new status') and differentiates from sibling read-only tools like 'get_linked_tickets' and 'get_ticket'. It also provides examples of common statuses, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by mentioning validation of transitions, but does not explicitly state when to use or avoid this tool, nor does it provide alternatives beyond the obvious sibling tools. It lacks guidance on prerequisites or edge cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedget_linked_tickets
    • First observedget_ticket
    • First observedupdate_ticket_status
Deploy Server
Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

TDQS

A3.8/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a distinct operation: retrieving a ticket, fetching linked tickets, and updating status. No overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent 'verb_noun' pattern in snake_case (get_ticket, get_linked_tickets, update_ticket_status), making them predictable.

Tool Count4/5

Three tools is on the lower end of the ideal range but still reasonable for a focused Jira server. Each tool serves a clear purpose without feeling sparse.

Completeness2/5

Missing essential CRUD operations such as create_ticket, search_tickets, or add_comment. Agents cannot create new tickets or perform most lifecycle actions.

Resources

Related MCP Connectors

Related MCP Servers

  • JIRA MCP Server

    Dsazz
    A
    license
    B
    quality
    D
    maintenance
    A Model Context Protocol server that integrates JIRA directly into Cursor IDE, allowing users to view assigned issues, get detailed information on specific tickets, and convert JIRA issues into local tasks without leaving their editor.
    14
    28 npm
    6
    TypeScript
    MIT

  • Jira MCP Server

    maximepeabody
    A
    license
    Not graded
    quality
    D
    maintenance
    A Simple Model Context Protocol server that enables AI assistants to interact with Jira, allowing operations like fetching tickets, adding comments, and updating ticket status.
    1
    Apache 2.0

  • MCP Jira

    TusharShahi
    F
    license
    Not graded
    quality
    D
    maintenance
    Model Context Protocol server that allows AI assistants to interact with Jira, supporting operations like creating tickets and fetching project information directly from the cursor.
    1
    -