Jira MCP Server v2.5.0

A complete MCP (Model Context Protocol) server for Jira integration, allowing AI assistants to interact with your Jira instance.

🚀 Installation

Via npx (Recommended)

npx @guhcostan/jira-mcp

Via npm global

npm install -g @guhcostan/jira-mcp
jira-mcp

Local Development

git clone https://github.com/guhcostan/jira-mcp.git
cd jira-mcp
npm install
npm run build

🔧 Configuration

1. Set up environment variables

Create a .env file in the project root:

JIRA_URL=https://your-jira-instance.com
JIRA_ACCESS_TOKEN=your-jira-access-token

Note: This server uses Jira Access Token with Bearer authentication (Jira Data Center/Server). For Jira Cloud, you may need to use Basic Auth.

2. Configure in Claude Desktop or Cursor

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

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@guhcostan/jira-mcp"],
      "env": {
        "JIRA_URL": "https://your-jira-instance.com",
        "JIRA_ACCESS_TOKEN": "your-jira-access-token"
      }
    }
  }
}

For local development, use:

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/path/to/your/jira-mcp/build/index.js"],
      "env": {
        "JIRA_URL": "https://your-jira-instance.com",
        "JIRA_ACCESS_TOKEN": "your-jira-access-token"
      }
    }
  }
}

3. Restart Claude Desktop / Cursor

Close and reopen the application completely to load the MCP server.

📚 Features

This MCP server provides 36 tools to interact with Jira:

📖 Read Operations (21 tools)

Issues

• jira_get_issue - Get issue details
• jira_search - Search issues with JQL
• jira_get_project_issues - Get project issues
• jira_batch_get_changelogs - Batch get changelogs
• jira_download_attachments - Get attachment info

Projects

• jira_get_all_projects - List all projects
• jira_get_project - Get project details
• jira_get_project_versions - Get project versions
• jira_search_projects - Search projects by pattern

Metrics & Analytics

• jira_get_issue_types - List all issue types
• jira_get_metrics_summary - Get consolidated metrics summary
• jira_get_metrics_by_project - Get detailed metrics by project

Other

• jira_get_worklog - Get issue worklogs
• jira_get_transitions - Get available transitions
• jira_search_fields - Search Jira fields
• jira_get_agile_boards - List agile boards
• jira_get_board_issues - Get board issues
• jira_get_sprints_from_board - Get board sprints
• jira_get_sprint_issues - Get sprint issues
• jira_get_issue_link_types - Get link types
• jira_get_user_profile - Get user information

✏️ Write Operations (15 tools)

Issues

• jira_create_issue - Create issue
• jira_batch_create_issues - Create multiple issues
• jira_update_issue - Update issue
• jira_delete_issue - Delete issue
• jira_assign_issue - Assign issue

Other

• jira_add_comment - Add comment
• jira_transition_issue - Change status
• jira_add_worklog - Add worklog
• jira_link_to_epic - Link to epic
• jira_create_sprint - Create sprint
• jira_update_sprint - Update sprint
• jira_create_issue_link - Create issue link
• jira_remove_issue_link - Remove link
• jira_create_version - Create version
• jira_batch_create_versions - Create multiple versions

💡 Usage Examples

Search Issues

// In Claude/Cursor, just ask:
"Find the last 10 open issues in project ABC"
"What are the critical bugs in the current sprint?"

Create Issue

"Create a Task issue in project XYZ with title 'Implement authentication'"

Manage Sprint

"List all active sprints from board 123"
"Move issue ABC-456 to sprint 789"

Advanced JQL

"Search issues with JQL: project = DEV AND status = 'In Progress' AND assignee = currentUser()"

Generate Metrics Reports (New in v2.5.0!)

// Search projects
"Find all projects that contain 'mobile' in the name"

// Get metrics summary
"Give me a summary of Tasks, Bugs, and Tech Debts for projects PROJ1, PROJ2, and PROJ3 created since 2024-10-01"

// Get detailed metrics by project
"Show me detailed metrics for each eLoyalty project, including Tasks, Bugs, and Tech Debts"

🔍 Tool Reference

jira_get_issue

Get details of a specific issue.

Parameters:

• issueKey (required): Issue key (e.g., PROJ-123)
• fields (optional): Fields to return (e.g., "summary,status,assignee")
• expand (optional): Expand fields (e.g., "changelog,renderedFields")

jira_search

Search issues using JQL.

Parameters:

• jql (required): JQL query (e.g., "project = PROJ AND status = Open")
• maxResults (optional): Maximum number of results (default: 50)
• startAt (optional): Starting index for pagination (default: 0)
• fields (optional): Fields to return

jira_create_issue

Create a new issue.

Parameters:

• project (required): Project key
• summary (required): Issue title
• issueType (required): Type (Task, Bug, Story, etc)
• description (optional): Description
• priority (optional): Priority (High, Medium, Low)
• assignee (optional): Assignee account ID
• labels (optional): Array of labels
• parentKey (optional): Parent issue key (for subtasks)

jira_transition_issue

Transition an issue to another status.

Parameters:

• issueKey (required): Issue key
• transition (required): Transition name or ID

jira_create_sprint

Create a new sprint.

Parameters:

• boardId (required): Board ID
• name (required): Sprint name
• startDate (optional): Start date (ISO 8601)
• endDate (optional): End date (ISO 8601)
• goal (optional): Sprint goal

jira_get_metrics_summary (New in v2.5.0)

Get consolidated metrics summary across multiple projects.

Parameters:

• projectKeys (required): Array of project keys (e.g., ["PROJ1", "PROJ2"])
• issueTypes (required): Array of issue type names (e.g., ["Task", "Bug"])
• createdSince (optional): Filter by creation date (YYYY-MM-DD format)

Example:

"Get metrics summary for projects ABC, DEF, and GHI showing Tasks and Bugs created since 2024-01-01"

jira_get_metrics_by_project (New in v2.5.0)

Get detailed metrics breakdown by individual project.

Parameters:

• projectKeys (required): Array of project keys
• issueTypes (required): Array of issue type names
• createdSince (optional): Filter by creation date (YYYY-MM-DD format)

Example:

"Show me detailed metrics for each project in the eLoyalty team"

🔐 Authentication

Jira Data Center/Server (Access Token)

This server uses Jira Access Token with Bearer authentication by default, ideal for Jira Data Center/Server instances:

Authorization: Bearer YOUR_ACCESS_TOKEN

Jira Cloud (Basic Auth)

If you use Jira Cloud, you may need to modify the authentication to Basic Auth in the code.

How to get a Jira Access Token

Step-by-step guide:

1. Open your Jira instance (e.g., https://your-jira-instance.com)
2. Click on your profile picture (top-right corner)
3. Select "Profile" from the dropdown menu
4. Navigate to "Personal Access Tokens" tab
   • Or go directly to: https://your-jira-instance.com/secure/ViewProfile.jspa?selectedTab=com.atlassian.pats.pats-plugin:jira-user-personal-access-tokens
5. Click "Create token"
6. Fill in the token details:
   • Name: Give it a meaningful name (e.g., "MCP Server")
   • Expiration: Choose an expiration date or "Never expire" (if available)
7. Copy the token immediately (you won't be able to see it again!)
8. Add the token to your .env file as JIRA_ACCESS_TOKEN

Important Notes:

• Store the token securely
• Don't commit the token to version control
• If you lose the token, you'll need to generate a new one
• The token inherits your user permissions

🛠️ Development

Project Structure

jira-mcp/
├── src/
│   └── index.ts          # Main MCP server
├── build/                # Compiled files
├── package.json
├── tsconfig.json
├── .env                  # Credentials (don't commit!)
├── .gitignore
└── README.md

Available Scripts

npm run build          # Compile TypeScript
npm run watch          # Compile in watch mode
npm run prepare        # Runs automatically on npm install

Test Locally

# Compile
npm run build

# Run directly
node build/index.js

📝 Important Notes

• ✅ Supports Jira Data Center/Server with Access Token
• ✅ 36 complete tools (21 read + 15 write)
• ✅ JQL support for advanced searches
• ✅ Batch operations for better performance
• ✅ Metrics & Analytics tools for generating reports (v2.5.0)
• ✅ Connection validation on startup - tools only appear if Jira is accessible
• ✅ Improved error handling with helpful error messages and suggestions
• ⚠️ Requires appropriate Jira permissions for each operation
• ⚠️ Rate limiting is applied by Jira

🐛 Troubleshooting

No tools appearing in Claude/Cursor

The server validates the connection on startup. If no tools appear, check the logs:

1. Connection validation failed - The server couldn't connect to Jira

   • Check your JIRA_URL is correct
   • Verify your JIRA_ACCESS_TOKEN is valid
   • Ensure Jira is accessible from your network

2. Look at the server logs for specific error messages:

   • In Claude Desktop: Check the application logs
   • The server will show: ✅ Connected to Jira as: [Your Name] or ❌ Jira connection failed: [error]

Error 401 - Unauthorized

• Check if the access token is correct
• Confirm you're using Bearer authentication with access token (not Basic Auth)
• Verify the token hasn't expired - tokens can expire, generate a new one if needed
• Ensure the token has the necessary permissions

Error 403 - Forbidden

• Your token doesn't have permission for this operation
• Check your Jira user permissions
• Some operations require admin privileges

Error 404 - Not Found

• The issue/project/resource doesn't exist
• Check the issue key or project key is correct
• Verify you have access to view the resource

Connection timeout or network errors

• Check your network connection
• Verify Jira server is accessible
• Check if there's a firewall blocking the connection

Server doesn't appear in Claude/Cursor at all

1. Check if the path in config is correct
2. Restart the application completely
3. Check Claude/Cursor logs for startup errors
4. Verify Node.js is installed and accessible

📄 License

MIT

👤 Author

Gustavo Neves

🔗 Links

• GitHub: https://github.com/guhcostan/jira-mcp
• npm: https://www.npmjs.com/package/@guhcostan/jira-mcp
• Issues: https://github.com/guhcostan/jira-mcp/issues

🤝 Contributing

Contributions are welcome! Feel free to open issues or pull requests.

1. Fork the project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request