🚀 AtlassianJira MCP Integration Server

Production-ready MCP server for Jira integration with dynamic configuration, time logging, task creation, issue updates, and bulk imports.

---

✨ Key Features

🔧 Dynamic Configuration

• No setup wizard needed - Configure through conversation with Claude
• Real-time configuration updates - Change settings without restart
• Intelligent suggestions - Get help with configuration
• Connection testing - Verify your Jira connection instantly

🛠️ Production Tools

• 📝 Time Logging - Log work time to Jira issues with comments
• 📋 Task Creation - Create comprehensive Jira issues with custom fields
• ✏️ Issue Updates - Update existing issues, change status, modify fields
• 📊 Bulk Import - Import multiple stories from spreadsheets
• ⚙️ Configuration Management - Dynamic Jira configuration tools

🌐 Remote Ready

• GitHub NPX deployment - Install directly from GitHub
• Zero local setup - Works immediately via Claude Desktop
• Secure configuration - Local config file with masked sensitive data

---

🚀 Quick Start (Remote Installation)

Method 1: Environment Variable Configuration (Recommended for MCP)

1. Add to Claude Desktop Configuration

Edit your Claude Desktop config file with environment variables:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "Jira Integration MCP": {
      "command": "npx",
      "args": ["-y", "github:techrivers/AtlassianJira-MCP-Integration"],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your-email@company.com",
        "JIRA_API_TOKEN": "your-api-token",
        "MCP_MODE": "true"
      }
    }
  }
}

2. Get Your Jira API Token

• Visit Atlassian API Tokens
• Create a new token
• Replace your-api-token in the configuration above

3. Restart Claude Desktop

4. Ready to Use! - No additional setup needed

Method 2: Dynamic Configuration (Interactive Setup)

1. Add Basic Configuration

{
  "mcpServers": {
    "jira-activitytimeline": {
      "command": "npx",
      "args": ["-y", "github:techrivers/AtlassianJira-MCP-Integration"]
    }
  }
}

2. Restart Claude Desktop

3. Configure Jira Connection

In your conversation with Claude, say:

"I need to set up my Jira connection"

Claude will use the configuration tools to help you set up:

• Jira URL (e.g., https://your-company.atlassian.net)
• Username (your email)
• API Token (from Atlassian)
• Project key (optional default)

4. Start Using

Once configured, you can immediately:

• Log time: "Log 2 hours to PROJ-123 for backend development"
• Create tasks: "Create a new story for user authentication"
• Update issues: "Update PROJ-123 status to In Progress and assign to me"
• Import stories: "Import these tasks from my spreadsheet"

---

🛠️ Available Tools

📝 Core Tools:

• logTime - Log work time to Jira issues with detailed comments
• createTask - Create comprehensive Jira issues with custom fields
• updateIssue - Update existing issues: fields, status, assignee, labels
• sheetToJiraStories - Bulk import stories from Excel/CSV files (Enhanced with file upload support)
• meetingNotesToJira - Parse meeting notes and create Jira issues from action items

⚙️ Configuration Tools:

• getJiraConfiguration - View current configuration status
• updateJiraConfiguration - Update Jira connection settings
• testJiraConnection - Test your Jira connection
• resetJiraConfiguration - Reset all configuration
• suggestJiraConfiguration - Get configuration suggestions

🚫 Temporarily Disabled:

• getTimeline - Requires Activity Timeline plugin API (see Re-enabling)

---

🔧 Configuration Management

Available Configuration Tools:

Tool	Description	Usage
getJiraConfiguration	View current configuration status	Check what's configured
updateJiraConfiguration	Update configuration settings	Change URL, credentials, etc.
testJiraConnection	Test your Jira connection	Verify setup works
resetJiraConfiguration	Reset all configuration	Start fresh
suggestJiraConfiguration	Get configuration suggestions	Get help with setup

Example Configuration Flow:

User: "I need to update my Jira URL"
Claude: [calls getJiraConfiguration to check current status]
Claude: [calls updateJiraConfiguration with new URL]
Claude: [calls testJiraConnection to verify]
Claude: "✅ Your Jira URL has been updated and tested successfully!"

Configuration File Location:

• macOS/Linux: ~/.jira-mcp.env
• Windows: C:\\Users\\{username}\\.jira-mcp.env

---

📊 Usage Examples

Initial Setup:

User: "Help me set up Jira integration"
Claude: [calls getJiraConfiguration]
Claude: "I can help you configure Jira. Let me start by checking your current setup..."
Claude: [calls suggestJiraConfiguration]
Claude: "Here's what you need to configure: URL, username, and API token."

Time Logging:

User: "Log 3 hours to PROJ-123 for fixing authentication bugs"
Claude: [calls logTime]
Claude: "✅ Successfully logged 3 hours to PROJ-123 with comment about authentication bugs."

Task Creation:

User: "Create a story for implementing user dashboard with high priority"
Claude: [calls createTask]
Claude: "✅ Created story PROJ-124: User Dashboard Implementation (High priority)"

Issue Updates:

User: "Update PROJ-123 to In Progress status and assign to john@company.com"
Claude: [calls updateIssue]
Claude: "✅ Updated PROJ-123: status → In Progress, assignee → john@company.com"

Bulk Import from Spreadsheets:

User: "Import these tasks from my Excel file"
Claude: [calls sheetToJiraStories]
Claude: "✅ Successfully imported 5 stories from your spreadsheet: PROJ-125, PROJ-126, PROJ-127, PROJ-128, PROJ-129"

Meeting Notes Processing:

User: "Parse this meeting note and create action items"
Claude: [calls meetingNotesToJira]
Claude: "✅ Found 3 actionable items and created: PROJ-130 (Review API), PROJ-131 (Fix login bug), PROJ-132 (Update docs)"

Configuration Updates:

User: "I need to switch to a different Jira instance"
Claude: [calls updateJiraConfiguration with new URL]
Claude: [calls testJiraConnection]
Claude: "✅ Successfully updated to new Jira instance and verified connection."

---

🚀 Deployment Options

Option 1: NPX (Recommended)

{
  "mcpServers": {
    "jira-activitytimeline": {
      "command": "npx",
      "args": ["-y", "github:techrivers/AtlassianJira-MCP-Integration"]
    }
  }
}

Option 2: Local Installation

# Clone and build locally
git clone https://github.com/techrivers/jiramcp.git
cd jiramcp
npm install
npm run build

{
  "mcpServers": {
    "jira-activitytimeline": {
      "command": "node",
      "args": ["./build/index.js"],
      "cwd": "/path/to/jiramcp"
    }
  }
}

Option 3: Global Installation

npm install -g github:techrivers/AtlassianJira-MCP-Integration

{
  "mcpServers": {
    "jira-activitytimeline": {
      "command": "jira-activitytimeline-server"
    }
  }
}

---

🔐 Security & Privacy

Configuration Security:

• ✅ Local storage - All configuration stored locally on your machine
• ✅ Masked sensitive data - API tokens never displayed in full
• ✅ No cloud storage - Configuration never sent to external servers
• ✅ Secure transmission - HTTPS-only communication with Jira

API Token Setup:

1. Visit Atlassian API Tokens
2. Create a new token with appropriate permissions
3. Use the token in your configuration (stored securely locally)

---

🔄 Re-enabling Activity Timeline Tools

The Activity Timeline tools are disabled because they require the Activity Timeline plugin API. To re-enable:

1. Install Activity Timeline Plugin in your Jira instance
2. Verify API Access - Check that /rest/activitytimeline/1.0/ endpoints are available
3. Contact Support - Request re-enabling of timeline tools
4. Tools Available After Re-enabling:
   • getTimeline - Retrieve activity timeline data
   • addTimeEntry - Add time entries to timeline
   • updateTimeEntry - Update existing time entries
   • deleteTimeEntry - Remove time entries
   • getTimeReport - Generate timeline reports

---

🔧 Advanced Configuration

Environment Variables (MCP Mode):

For MCP deployment, use environment variables in your configuration:

{
  "mcpServers": {
    "Jira Integration MCP": {
      "command": "npx",
      "args": ["-y", "github:techrivers/AtlassianJira-MCP-Integration"],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your-email@company.com",
        "JIRA_API_TOKEN": "your-api-token",
        "MCP_MODE": "true",
        "JIRA_PROJECT_KEY": "PROJ",
        "JIRA_DEFAULT_ASSIGNEE": "team-lead@company.com",
        "JIRA_DEFAULT_PRIORITY": "Medium"
      }
    }
  }
}

Required Environment Variables:

• JIRA_URL - Your Jira instance URL
• JIRA_USERNAME - Your Jira username/email
• JIRA_API_TOKEN - Your Jira API token
• MCP_MODE - Set to "true" to enable MCP-compliant mode

Optional Environment Variables:

• JIRA_PROJECT_KEY - Default project for task creation
• JIRA_DEFAULT_ASSIGNEE - Default assignee for new tasks
• JIRA_DEFAULT_PRIORITY - Default priority level
• SKIP_UI_SETUP - Set to "true" to skip UI setup completely

Multiple Jira Instances:

The dynamic configuration system supports switching between different Jira instances:

User: "Switch to my staging Jira environment"
Claude: [calls updateJiraConfiguration with staging URL]
Claude: "✅ Switched to staging environment. Ready to work with staging Jira."

---

📈 Troubleshooting

Common Issues:

Node.js Version Incompatibility:

❌ Node.js Version Incompatibility Error
Current Node.js version: v16.13.0
Required Node.js version: >=20.0.0

Solutions:

1. Update Node.js: Visit nodejs.org and install v20+ (LTS)
2. Clear NPX cache: npx clear-npx-cache
3. Restart Claude Desktop completely after updating Node.js
4. Use explicit Node.js path in Claude Desktop config:

   {
     "mcpServers": {
       "jira-activitytimeline": {
         "command": "/usr/local/bin/node",
         "args": ["/usr/local/bin/npx", "-y", "github:techrivers/AtlassianJira-MCP-Integration"]
       }
     }
   }
   

📋 See CLAUDE_DESKTOP_SETUP.md for detailed setup instructions.

Connection Failed:

User: "My Jira connection isn't working"
Claude: [calls testJiraConnection]
Claude: [calls getJiraConfiguration]
Claude: "I found the issue. Let me help you update your API token..."

Configuration Problems:

User: "I'm getting configuration errors"
Claude: [calls getJiraConfiguration]
Claude: [calls suggestJiraConfiguration]
Claude: "Here are the missing configuration fields and suggestions..."

Reset Configuration:

User: "I want to start over with my configuration"
Claude: [calls resetJiraConfiguration with confirmation]
Claude: "✅ Configuration reset. Let's set up your Jira connection again..."

Debug Mode:

Set DEBUG=true in your environment to see detailed logging.

---

🏗️ Development

Project Structure:

src/
├── index.ts                    # Main MCP server entry point
├── tools/                      # MCP tool implementations
│   ├── configurationTools.ts   # Dynamic configuration tools
│   ├── createTask.ts           # Task creation
│   ├── updateIssue.ts          # Issue updates
│   ├── logTime.ts              # Time logging
│   ├── sheetToJiraStories.ts   # Enhanced bulk import with file upload
│   ├── meetingNotesToJira.ts   # Meeting notes parser with action detection
│   └── activityTimeline.ts     # Timeline tools (disabled)
└── utils/                      # Shared utilities
    ├── configManager.ts        # Dynamic configuration system
    ├── jiraFieldMapper.ts      # Field mapping and validation
    ├── jiraIssueCreator.ts     # Jira API helpers
    └── types.ts                # TypeScript definitions

Local Development:

git clone https://github.com/techrivers/jiramcp.git
cd jiramcp
npm install
npm run dev

Building:

npm run build

Testing:

# Test with --help
node build/index.js --help

# Test with --version  
node build/index.js --version

---

🤝 Contributing

We welcome contributions! This server demonstrates:

• Dynamic configuration patterns for MCP servers
• Conversational setup instead of traditional wizards
• Production-ready deployment strategies
• Security best practices for credential management

Development Process:

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Make your changes following existing patterns
4. Add TypeScript types and JSDoc comments
5. Test your changes (npm run build && npm run dev)
6. Commit changes (git commit -m 'feat: add amazing feature')
7. Push to branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Code Style:

• Use TypeScript for all new code
• Follow existing naming conventions
• Add JSDoc comments for public functions
• Keep functions small and focused
• Include comprehensive error handling

---

📄 License

MIT License - see LICENSE file for details.

---

🎯 Why This Architecture?

This server demonstrates a dynamic configuration approach that's perfect for complex, ongoing workflows:

Traditional Setup vs. Dynamic Configuration:

Traditional	Dynamic
One-time setup wizard	Conversational configuration
Static configuration	Runtime updates
Manual credential management	Intelligent suggestions
Restart required for changes	Hot configuration updates
Error-prone initial setup	Guided, contextual help

Perfect for Jira Workflows:

• Multi-project environments - Switch between projects seamlessly
• Credential rotation - Update API tokens without restart
• Team collaboration - Share configuration patterns
• Development stages - Switch between dev/staging/prod instances

---

🚀 Ready to boost your Jira productivity? Add the server to Claude Desktop and start your conversational configuration journey!