@devpuccino/mcp-jira

Connect Claude to Jira with Model Context Protocol (MCP) - Create issues, search, add comments, and automate your workflow with AI assistance.

🚀 Quick Start

Option 1: Use with npx (Recommended)

# No installation needed!
npx @devpuccino/mcp-jira --list-tools

Option 2: Install Globally

npm install -g @devpuccino/mcp-jira
mcp-jira --list-tools

Option 3: Use with Claude Desktop ⭐

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["@devpuccino/mcp-jira"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_TOKEN": "your-api-token"
      }
    }
  }
}

Then restart Claude Desktop and start chatting! 🎉

✨ Features

• 32 MCP Tools - Full Jira API coverage
• 10 Tool Categories - Organized for easy access
• Selective Tool Loading - Save tokens by loading only what you need
• MCP Standard Compliant - 100% compliance score
• ADF Format Support - Automatic plain text to ADF conversion
• CLI & MCP Modes - Use standalone or with AI assistants
• Optimized Package Size - Only 37 KB (gzipped)

🔧 Installation

Global Installation

npm install -g @devpuccino/mcp-jira

Verify Installation

mcp-jira --list-tools

📖 Usage Examples

1. Standalone CLI Mode

List Available Tools

mcp-jira --list-tools

Output:

Available tools:
  - get-fields
  - get-field-by-key
  - create-field
  - get-projects
  - get-project-by-key
  - create-issue
  - get-issue
  - update-issue
  - delete-issue
  - search-issues
  - get-comments
  - add-comment
  ... (22 more)

List Categories

mcp-jira --list-categories

Output:

Available categories:
  - fields
  - projects
  - issues
  - comments
  - transitions
  - attachments
  - worklogs
  - status
  - metadata
  - properties

2. Selective Tool Loading (Save Tokens! 💰)

Load only the tools you need to reduce token usage by up to 95%!

Load Specific Tools

# Load only issue operations
mcp-jira --tools=get-issue,create-issue,search-issues

# Load by category (7 tools, saves 78% tokens)
mcp-jira --categories=issues,comments

# Developer daily driver (12 tools)
mcp-jira --categories=issues,comments,attachments,transitions

Exclude Destructive Operations

# Read-only mode (no delete operations)
mcp-jira --exclude=delete-issue,delete-attachment,delete-worklog-by-id

Minimal Setup (2 tools, saves 94% tokens)

mcp-jira --tools=get-issue,search-issues

3. With Claude Desktop 🤖

Basic Configuration

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["@devpuccino/mcp-jira"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_TOKEN": "your-api-token"
      }
    }
  }
}

Load Specific Tools Only

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": [
        "@devpuccino/mcp-jira",
        "--categories=issues,comments"
      ],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_TOKEN": "your-api-token"
      }
    }
  }
}

Example Interaction

You:

"Create a new task in PROJ project for adding login feature with high priority"

Claude (using mcp-jira):

✅ Created issue PROJ-123: "Add login feature"

• Type: Task
• Priority: High
• Status: To Do

You:

"Search for all open bugs in PROJ project assigned to me"

Claude (using mcp-jira):

Found 3 open bugs:

• PROJ-45: Login button not working
• PROJ-67: Password reset fails
• PROJ-89: Session timeout issue

You:

"Add a comment to PROJ-45 saying we're investigating the issue"

Claude (using mcp-jira):

✅ Comment added to PROJ-45: "We're investigating the issue and will update soon."

4. Development Setup

Using with Specific Tools

# For bug triage workflow
mcp-jira --tools=get-issue,search-issues,add-comment,transition-issue

# For time tracking
mcp-jira --categories=worklogs,issues

# For project management
mcp-jira --categories=projects,issues,status

🔐 Environment Variables

Required

Set these before running:

export JIRA_BASE_URL="https://your-domain.atlassian.net"
export JIRA_EMAIL="[email protected]"
export JIRA_TOKEN="your-api-token"

Getting Your Jira API Token

1. Go to: https://id.atlassian.com/manage-profile/security/api-tokens
2. Click Create API token
3. Give it a label (e.g., "MCP Server")
4. Copy the token
5. Use it in the environment variable

Finding Your Jira Domain

Your Jira domain is in the URL:

https://your-domain.atlassian.net
                ↑
           This part

Example: If your URL is https://devpuccino.atlassian.net, then:

export JIRA_BASE_URL="https://devpuccino.atlassian.net"

🛠️ Available Tools

Issues (5 tools)

• create-issue - Create new issues
• get-issue - Get issue details
• update-issue - Update issue fields
• delete-issue - Delete issues (use carefully!)
• search-issues - Search with JQL queries

Comments (2 tools)

• get-comments - List issue comments
• add-comment - Add comment to issue

Projects (2 tools)

• get-projects - List all projects
• get-project-by-key - Get project details

Attachments (3 tools)

• get-attachments - List attachments
• post-attachments - Upload files
• delete-attachment - Remove attachments

Worklogs (5 tools)

• get-worklog - List worklogs
• post-worklog - Log time
• get-worklog-by-id - Get specific worklog
• update-worklog - Update worklog
• delete-worklog-by-id - Delete worklog

And More...

• Fields (3 tools) - Custom field management
• Transitions (2 tools) - Workflow transitions
• Status (2 tools) - Status information
• Metadata (4 tools) - Edit metadata, watchers
• Properties (4 tools) - Issue properties

Total: 32 tools across 10 categories

💡 Common Use Cases

1. Daily Standup

# Load tools for status updates
mcp-jira --categories=issues,comments

Ask Claude:

"What issues are assigned to me that were updated yesterday?"

2. Sprint Planning

# Load tools for backlog management
mcp-jira --categories=issues,comments,worklogs

Ask Claude:

"Show me all unresolved issues in PROJ project sorted by priority"

3. Code Review

# Load tools for review workflow
mcp-jira --tools=get-issue,search-issues,add-comment,transition-issue

Ask Claude:

"Move PROJ-123 to 'In Review' and add a comment that PR is ready"

4. Time Tracking

# Load time tracking tools
mcp-jira --categories=worklogs

Ask Claude:

"Log 2 hours on PROJ-45 for today with comment 'Fixed login bug'"

📊 Token Optimization

Load only what you need to save tokens:

| Configuration | Tools | Token Usage | Use Case | |---------------|-------|-------------|----------| | All Tools | 32 | 100% | Full access | | Issues + Comments | 7 | ~22% | Daily development | | Minimal | 2 | ~6% | Read-only queries | | Developer Daily | 12 | ~37% | Regular workflow |

Example:

# Save 78% tokens for simple workflows
mcp-jira --categories=issues,comments

🔒 Security Best Practices

1. Use Environment Variables

# ✅ Good
export JIRA_TOKEN="your-token"
mcp-jira

# ❌ Bad - Don't hardcode tokens!
# Edit source code with token inside

2. Use .env File (Development)

Create .env file:

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

Then load with:

set -a && source .env && set +a && mcp-jira

3. Never Commit Tokens

Add to .gitignore:

.env
*.pem
*.key

🧪 Development

Build from Source

git clone https://bitbucket.org/devpuccino/mcp-jira.git
cd mcp-jira
npm install
npm run build

Run Tests

# Unit tests
npm test

# Coverage report
npm run test:coverage

# MCP compliance check
node scripts/check-mcp-standard.js

CLI Tests

bash scripts/test-npx-cli.sh

📚 Documentation

• CLI Usage Guide - Command-line options
• Tool Selection Guide - Optimize tool loading
• MCP Architecture - How MCP works
• Jira API Reference - API details
• ADF Format Guide - Working with ADF format

🆘 Troubleshooting

"Command not found: mcp-jira"

# Check installation
npm list -g @devpuccino/mcp-jira

# Reinstall if needed
npm install -g @devpuccino/mcp-jira

"Authentication failed"

# Verify environment variables
echo $JIRA_EMAIL
echo $JIRA_BASE_URL

# Test token
curl -u your-email:your-token \
  https://your-domain.atlassian.net/rest/api/3/myself

"No tools loaded"

# Check available tools
mcp-jira --list-tools

# Load all tools (default)
mcp-jira

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (npm test)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📄 License

This project is licensed under the ISC License - see the LICENSE file for details.

🔗 Links

• NPM Package: https://www.npmjs.com/package/@devpuccino/mcp-jira
• Repository: https://bitbucket.org/devpuccino/mcp-jira
• MCP Documentation: https://modelcontextprotocol.io
• Jira API Docs: https://developer.atlassian.com/cloud/jira/platform/rest/v3/

🌟 Show Your Support

If you find this MCP server helpful, please:

• ⭐ Star the repository on Bitbucket
• 📦 Install from NPM to show download stats
• 🐛 Report bugs and suggest features
• 📝 Share with your team!

Built with ❤️ by DevPuccino | MCP Standard Compliant (100%)