Jira Structure MCP Server

A Model Context Protocol (MCP) server for managing hierarchical folder structures in Jira using the Tempo Structure plugin. Create folders, organize issues, and build complex hierarchies through natural language with Claude and other AI assistants.

🚀 Quick Start

Prerequisites

• Jira Data Center with Tempo Structure plugin installed
• Jira personal access token with appropriate permissions

Configuration

Claude Code

Add the server using the Claude Code CLI:

claude mcp add -s user \
    jira-structure \
    npx mcp-jira-structure@latest \
    -e "JIRA_URL=https://jira.example.com" \
    -e "JIRA_PERSONAL_TOKEN=your_personal_access_token"

Manual Configuration (Any MCP Client)

Alternatively, add this configuration to your MCP client's configuration file:

{
  "mcpServers": {
    "jira-structure": {
      "command": "npx",
      "args": ["mcp-jira-structure@latest"],
      "type": "stdio",
      "env": {
        "JIRA_URL": "https://jira.example.com",
        "JIRA_PERSONAL_TOKEN": "your_personal_access_token"
      }
    }
  }
}

✨ Features

• 📁 Folder Management - Create virtual folders to organize issues hierarchically
• 🔍 Discovery Tools - List structures, browse hierarchies, search for items
• ✏️ Organization - Move items, delete from structure, rename folders
• 🔗 Issue Integration - Add existing Jira issues to structures
• 🔄 Version Control - Automatic conflict resolution with retry logic
• 🎯 Type Safety - Full TypeScript support with comprehensive types
• 🛡️ Error Handling - Robust error handling with user-friendly messages

🛠️ Available Tools

The server provides 11 MCP tools for Structure operations:

Discovery Tools (3)

• structure_list - List all accessible structures
• structure_get_hierarchy - Get hierarchical tree with full details
• structure_find_item - Search items by name with context

Creation Tools (2)

• structure_create_folder - Create virtual folders
• structure_add_issue - Add existing Jira issues to structure

Organization Tools (2)

• structure_move_item - Reposition items in hierarchy
• structure_delete_item - Remove items from structure

Advanced Tools (2)

• structure_get_item_details - Query detailed item information
• structure_rename_item - Rename folders or update properties

💡 Example Queries

• "List all my structures"
• "Show me the hierarchy of structure 1"
• "Create a folder called 'Sprint 42' under the Projects folder"
• "Find all items named 'Backend' in structure 1"
• "Add issue PROJ-12345 under the Backend folder"
• "Move the API folder under Services"
• "Rename the folder to 'Q4 Projects'"

📋 Common Workflows

Recommended Usage Pattern

The typical workflow follows these steps:

1. Get list of structures - Use structure_list to see all available structures
2. Pick a structure - Select the structure ID you want to work with
3. Search within structure - Use structure_find_item with the specific structure ID

Example workflow:

1. "List all structures" → Returns available structures
2. "I want to work with Project Delivery (structure ID 1)"
3. "Find 'Backend Projects' in structure 1" → Returns rowId
4. "Create a folder under that rowId"

Adding Issues to Structure

1. Create issue with Jira MCP: "Create epic for Responsive Design"
2. Find context: "Find the Mobile Development folder"
3. Add to structure: "Add issue under that folder"

🏗️ Development

From Source

# Clone and setup
git clone https://github.com/evrimalacan/mcp-jira-structure.git
cd mcp-jira-structure
npm install

# Build
npm run build

# Development mode
npm run dev

# Run tests
npm test                # Unit tests
npm test -- --coverage  # With coverage report

Project Structure

src/
├── index.ts              # MCP server setup
├── config.ts             # Environment configuration
├── structureClient.ts    # Jira Structure API client
├── types.ts              # TypeScript type definitions
├── utils/
│   ├── formulaParser.ts  # Parse Structure formulas into trees
│   └── versionManager.ts # Handle version conflicts
└── tools/
    ├── discovery.ts      # Discovery tools (list, hierarchy, find)
    ├── creation.ts       # Creation tools (folder, issue)
    ├── organization.ts   # Organization tools (move, delete)
    └── advanced.ts       # Advanced tools (details, rename)

🐛 Troubleshooting

Common Issues

"Authentication failed"

• Verify your Jira personal token is correct
• Ensure token has Structure plugin permissions

"Permission denied"

• Check your user has access to the structure
• Verify write permissions for modification operations

"Version conflict"

• Automatic retry is built-in (3 attempts)
• If persists, structure may be heavily contested

"Parent folder not found"

• Verify the underRowId exists
• Use structure_find_item to locate correct parent

📚 Documentation

• API Documentation - Technical API details
• Tempo Structure Docs - Official plugin documentation

🔑 Key Concepts

RowId

• Unique identifier for an item's position in the structure
• Different from Jira issue ID
• Same issue can have multiple rowIds if added multiple times

Folders

• Virtual organizational containers
• Not actual Jira issues
• Can contain folders and issues

Version Control

• Structure uses optimistic locking
• Each modification requires current version
• Automatic retry on conflicts (built-in)

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Add tests for your changes
4. Ensure build passes (npm run build)
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

MIT License - see LICENSE file for details.

🌟 Support

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• 📖 Documentation: See TEMPO_STRUCTURE_API.md

Built for Tempo Structure plugin | Powered by MCP