mcp-jira-stdio

MCP Jira Server

Jira API と連携するための Model Context Protocol（MCP）サーバーです。MCP クライアント（Claude Desktop など）から Jira の課題やプロジェクトを直接読み取り、書き込み、管理できます。

⚡ Claude Code へのクイックインストール

この MCP サーバーを Claude Code に追加する最も速い方法です。

claude mcp add jira npx mcp-jira-stdio@latest \
  --env JIRA_BASE_URL=https://yourcompany.atlassian.net \
  --env [email protected] \
  --env JIRA_API_TOKEN=your-api-token

値を実際の Jira 認証情報に置き換えてください。

• JIRA_BASE_URL: Jira インスタンスの URL（例：https://yourcompany.atlassian.net）
• JIRA_EMAIL: Jira アカウントのメールアドレス
• JIRA_API_TOKEN: Jira API トークン（こちらで生成）

これで完了です。サーバーは自動的に設定され、すぐに使用できます。

別の方法：手動設定

手動で設定する場合や Claude Desktop を使用する場合は、以下の設定セクションをご覧ください。

🚀 クイックスタート

1. 前提条件

• Node.js v20 以降
• Jira インスタンス（Cloud または Server）
• Jira API トークン

2. インストール

# Install from npm
npm install -g mcp-jira-stdio

# Or install locally in your project
npm install mcp-jira-stdio

開発用インストール

# Clone the repository
git clone https://github.com/freema/mcp-jira-stdio.git
cd mcp-jira-stdio

# Install dependencies
npm install
# or using Task runner
task install

# Build the project
npm run build
# or
task build

3. Jira API のセットアップ

1. Jira インスタンスの設定に移動します
2. API トークンを作成します。
   • Jira Cloud：アカウント設定 → セキュリティ → API トークンの作成と管理に移動します
   • Jira Server：ユーザー名とパスワードを使用します（またはアプリケーションパスワードを作成します）
3. Jira のベース URL を確認します（例：https://yourcompany.atlassian.net）

4. 設定

用意されているサンプルから .env ファイルを作成します。

# Copy the example environment file
cp .env.example .env

# Edit .env with your actual Jira credentials
# Or use Task runner:
task env

.env の内容の例：

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

注： API トークンは https://id.atlassian.com/manage-profile/security/api-tokens で生成してください。

5. 接続のテスト

# Test Jira connection
task jira:test

# List visible projects
task jira:projects

6. MCP クライアントの設定

Claude Code の場合

クイックインストールコマンドを使用します（推奨）。

claude mcp add jira npx mcp-jira-stdio@latest \
  --env JIRA_BASE_URL=https://yourcompany.atlassian.net \
  --env [email protected] \
  --env JIRA_API_TOKEN=your-api-token

Claude Desktop の場合

Claude Desktop の設定ファイルに追加します。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "jira": {
      "command": "mcp-jira-stdio",
      "env": {
        "JIRA_BASE_URL": "https://your-instance.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

別の方法：npx を使用

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["mcp-jira-stdio"],
      "env": {
        "JIRA_BASE_URL": "https://your-instance.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

設定を追加したら、Claude Desktop を再起動してください。

📦 利用可能なツール

プロジェクト

• jira_get_visible_projects：ユーザーが閲覧できるすべてのプロジェクトを取得します。
• jira_get_project_info：プロジェクトの詳細情報（コンポーネント、バージョン、ロール、インサイト）を取得します。

課題

• jira_get_issue：キーを指定して課題の詳細を取得します（フィールド／展開の指定は任意です）。
• jira_search_issues：ページネーションとフィールドを指定して、JQL で Jira の課題を検索します。
• jira_create_issue：プロジェクトに新しい課題を作成します（タイプ、優先度、担当者、ラベル、コンポーネント）。
• jira_update_issue：既存の課題を更新します（要約、説明、優先度、担当者、ラベル、コンポーネント、修正バージョン）。
• jira_create_subtask：親課題の下にサブタスクを作成します（サブタスクのタイプを自動検出します）。

コメント

• jira_add_comment：課題にコメントを追加します（グループ／ロールによる公開範囲の指定は任意です）。

メタデータとユーザー

• jira_get_create_meta：プロジェクトの作成メタデータを取得し、使用可能なすべてのフィールド（カスタムフィールドを含む）と、各フィールドで許可される値を表示します。課題の作成前に必須フィールドを確認するために不可欠です。
• jira_get_issue_types：課題タイプを一覧表示します（プロジェクトごとの指定も可能です）。
• jira_get_users：ユーザーを検索します（クエリ、ユーザー名、accountId による検索）。
• jira_get_priorities：使用可能な優先度を一覧表示します。
• jira_get_statuses：使用可能なステータスを一覧表示します（全体またはプロジェクト別）。
• jira_get_custom_fields：Jira のすべてのカスタムフィールドを、タイプとスキーマとともに一覧表示します。

自分の作業

• jira_get_my_issues：現在のユーザーに割り当てられた課題を取得します（更新日時順）。

🛠️ 開発

開発コマンド

# Development mode with hot reload
npm run dev
task dev

# Build for production
npm run build
task build

# Type checking
npm run typecheck
task typecheck

# Linting
npm run lint
task lint

# Format code
npm run format
task fmt

# Run all checks
npm run check
task check

MCP Inspector

Inspector を使用して MCP サーバーをデバッグします。

# Run inspector (production build)
npm run inspector
task inspector

# Run inspector (development mode)
npm run inspector:dev
task inspector:dev

注意：

• Jira への接続は起動を妨げなくなりました。Jira の環境変数が設定されていない場合でもサーバーは起動し、ツールを一覧表示します。JIRA_BASE_URL、JIRA_EMAIL、JIRA_API_TOKEN を設定するまでは、ツールの呼び出しは明確な認証エラーで失敗します。
• 接続テストは開発／テスト環境（NODE_ENV=development または test）でのみ実行されます。失敗してもログに記録されるだけで、サーバーは終了しないため、Inspector で引き続きツールを表示できます。

テスト

# Run tests
npm test
task test

# Run tests with coverage
npm run test:coverage
task test:coverage

# Watch mode
npm run test:watch
task test:watch

📋 プロジェクト構成

src/
├── index.ts              # Entry point & MCP server setup
├── config/
│   └── constants.ts      # API configuration & constants
├── tools/
│   ├── index.ts          # Tool exports
│   └── get-visible-projects.ts  # Get visible projects tool
├── types/
│   ├── common.ts         # Common types & interfaces
│   ├── jira.ts           # Jira API types
│   └── tools.ts          # Tool input/output schemas
└── utils/
    ├── jira-auth.ts      # Jira authentication & client
    ├── validators.ts     # Input validation with Zod
    ├── formatters.ts     # Response formatting
    ├── error-handler.ts  # Error handling
    └── api-helpers.ts    # Jira API helpers

🔧 ツールの使用例

表示可能なプロジェクトを取得する

// List all projects
jira_get_visible_projects({});

// List projects with additional details
jira_get_visible_projects({
  expand: ['description', 'lead', 'issueTypes'],
});

// List recent projects only
jira_get_visible_projects({
  recent: 10,
});

❗ トラブルシューティング

よくある問題

「認証に失敗しました」

• API トークンが正しいことを確認してください
• メールアドレスが Jira アカウントと一致していることを確認してください
• Jira のベース URL が正しいことを確認してください（末尾にスラッシュを付けないでください）

「接続に失敗しました」

• Jira インスタンスにアクセスできることを確認してください
• ネットワーク接続を確認してください
• Jira REST API が有効になっていることを確認してください

「権限がありません」

• アカウントに必要な権限があることを確認してください
• Jira のプロジェクト権限を確認してください
• 正しい Jira インスタンスを使用していることを確認してください

MCP の接続に関する問題

• ビルド済みのバージョン（dist/index.js）を使用していることを確認してください
• Claude Desktop の設定で Node.js のパスが正しいことを確認してください
• Claude Desktop のログでエラーを確認してください
• task inspector を使用してデバッグしてください

npx で複数のインスタンスを実行したときにタイムアウトする

複数の Claude Code セッションを同時に実行してタイムアウトが発生する場合、原因は MCP サーバー自体ではなく、npx のキャッシュ／レジストリのロックです。各インスタンスがパッケージを検証しようとするため、競合が発生します。解決するには、代わりにパッケージをグローバルにインストールしてください。

npm install -g mcp-jira-stdio
claude mcp add jira mcp-jira-stdio \
  --env JIRA_BASE_URL=... \
  --env JIRA_EMAIL=... \
  --env JIRA_API_TOKEN=...

デバッグコマンド

# Test Jira connection
task jira:test

# List projects (test API connectivity)
task jira:projects

# Run MCP inspector for debugging
task inspector:dev

# Check all configuration
task check

Inspector に SSE エラーが表示され、サーバーがすぐに終了する場合は、無効な認証情報によって早期終了を強制していないことを確認してください。現在の動作では、認証情報がない場合でもサーバーは終了しません。ツールを実行するには、Jira の環境変数をエクスポートしてください。

export JIRA_BASE_URL="https://your-instance.atlassian.net"
export JIRA_EMAIL="[email protected]"
export JIRA_API_TOKEN="your-api-token"
npm run inspector

🔍 環境変数

変数	必須	説明	例
JIRA_BASE_URL	はい	Jira インスタンスの URL	https://company.atlassian.net
JIRA_EMAIL	はい	Jira のメールアドレス	[email protected]
JIRA_API_TOKEN	はい	Jira API トークン	ATxxx...
NODE_ENV	いいえ	環境モード	development または production

🤝 コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. テストとリンティングを実行します（task check）
4. 変更をコミットします（git commit -m 'Add some amazing feature'）
5. ブランチにプッシュします（git push origin feature/amazing-feature）
6. プルリクエストを作成します

📄 ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については、LICENSE ファイルをご覧ください。

MCP 設定

この MCP サーバーを対話的に使用するよう Claude Desktop を設定します。

npm run setup:mcp

このスクリプトは次の処理を行います。

• 必要に応じてプロジェクトをビルドし、Node のパスを検出します
• JIRA_BASE_URL、JIRA_EMAIL、JIRA_API_TOKEN の入力を求めます
• Claude Desktop の設定に jira エントリを保存するか、JSON を出力します
• オプションで開発用のローカル .env を生成します