jira-server-mcp

saggl/jira-server-mcp

3.2

If you are the rightful owner of jira-server-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A Model Context Protocol (MCP) server for integrating Jira Server/Data Center with AI applications like Claude.

Tools
5
Resources
0
Prompts
0

Jira Server MCP

A Model Context Protocol (MCP) server for Jira Server/Data Center integration with Claude and other LLM applications.

Features

This MCP server provides comprehensive access to Jira Server/Data Center functionality through the Model Context Protocol, enabling AI assistants like Claude to:

Search & Read Operations

  • search_issues: Search for issues using JQL (Jira Query Language)
  • get_issue: Get detailed information about specific issues
  • list_projects: List all accessible projects
  • get_project: Get detailed project information

Create & Update Operations

  • create_issue: Create new issues with custom fields
  • update_issue: Update existing issues
  • add_comment: Add comments to issues

Workflow Management

  • get_transitions: Get available workflow transitions
  • transition_issue: Move issues through workflow states
  • assign_issue: Assign/unassign issues to users

User Management

  • get_user: Get user information
  • search_users: Search for users by name or email

Metadata

  • get_issue_types: Get available issue types
  • get_priorities: Get priority levels
  • get_statuses: Get status values

Agile/Sprint Features

  • get_boards: List all Agile boards
  • get_sprints: Get sprints for a board
  • get_sprint_issues: Get issues in a sprint
  • move_to_sprint: Move issues to sprints (coming soon)

Requirements

  • Node.js 18 or higher
  • Jira Server/Data Center 8.x or 9.x
  • Valid Jira Server credentials (username and password)

Installation

From Source

  1. Clone this repository:
git clone <repository-url>
cd jira-server-mcp
  1. Install dependencies:
npm install
  1. Build the project:
npm run build

Global Installation (Optional)

npm install -g .

Configuration

Environment Variables

Create a .env file in the project root (or set these environment variables):

# Jira Server URL (without trailing slash)
JIRA_HOST=https://jira.yourcompany.com

# Jira Server Username
JIRA_USERNAME=your-username

# Jira Server Password or Personal Access Token
JIRA_PASSWORD=your-password

# Jira API Version (2 or latest)
JIRA_API_VERSION=2

# Optional: Strict SSL verification (true/false)
# Set to false if using self-signed certificates (not recommended for production)
JIRA_STRICT_SSL=true

Copy the example configuration:

cp .env.example .env
# Then edit .env with your Jira Server details

Claude Desktop Configuration

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "jira-server": {
      "command": "node",
      "args": ["/absolute/path/to/jira-server-mcp/dist/index.js"],
      "env": {
        "JIRA_HOST": "https://jira.yourcompany.com",
        "JIRA_USERNAME": "your-username",
        "JIRA_PASSWORD": "your-password",
        "JIRA_API_VERSION": "2",
        "JIRA_STRICT_SSL": "true"
      }
    }
  }
}

Replace /absolute/path/to/jira-server-mcp with the actual path to your installation.

Usage Examples

With Claude Desktop

Once configured, you can interact with Jira Server through natural language in Claude Desktop:

Search for issues:

Show me all open bugs in the PROJECT project

Get issue details:

Get the details of issue PROJ-123

Create an issue:

Create a new bug in project PROJ with summary "Login page not loading"
and description "Users are reporting that the login page fails to load"

Update an issue:

Update PROJ-123 to set priority to High and assign it to john.doe

Workflow transitions:

Move PROJ-123 to In Progress status

Agile operations:

Show me all sprints for board 5 and list the issues in the active sprint

With MCP Inspector (Testing)

For development and testing:

npm run inspector

This will start the MCP Inspector, allowing you to test all tools interactively.

Direct API Usage

import { createJiraClient } from './jira-client.js';

// Initialize client
const client = createJiraClient();

// Search issues
const results = await client.searchIssues('project = PROJ AND status = Open');

// Get issue
const issue = await client.getIssue('PROJ-123');

// Create issue
const newIssue = await client.createIssue({
  projectKey: 'PROJ',
  summary: 'New issue',
  issueTypeName: 'Bug',
  description: 'Issue description',
  priorityName: 'High'
});

JQL (Jira Query Language) Examples

JQL is powerful for searching issues:

# All open issues in a project
project = PROJ AND status = Open

# Issues assigned to you
assignee = currentUser() ORDER BY created DESC

# High priority bugs
priority = High AND type = Bug

# Issues created this week
created >= startOfWeek()

# Issues in a specific sprint
sprint = "Sprint 1"

# Complex queries
project = PROJ AND status IN (Open, "In Progress") AND assignee = currentUser() AND priority IN (High, Critical) ORDER BY priority DESC, created ASC

Development

Project Structure

jira-server-mcp/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── jira-client.ts        # Jira API client wrapper
│   ├── tools/                # MCP tool implementations
│   ├── resources/            # MCP resources
│   ├── schemas/              # Zod validation schemas
│   │   └── tool-schemas.ts
│   └── types/                # TypeScript type definitions
│       └── jira-types.ts
├── dist/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

Build Scripts

# Build the project
npm run build

# Watch mode (auto-rebuild on changes)
npm run watch

# Development mode with tsx
npm run dev

# Run MCP Inspector for testing
npm run inspector

Adding New Tools

  1. Define the input schema in src/schemas/tool-schemas.ts
  2. Add the tool to the tools list in src/index.ts
  3. Implement the tool handler in the CallToolRequestSchema handler
  4. Add corresponding method in src/jira-client.ts if needed
  5. Rebuild the project

Troubleshooting

Authentication Issues

  • 401 Unauthorized: Check your username and password
  • 403 Forbidden: User doesn't have permission for the requested operation
  • Verify JIRA_HOST is correct and accessible
  • For self-signed certificates, set JIRA_STRICT_SSL=false (not recommended for production)

Connection Issues

  • Ensure Jira Server is accessible from your network
  • Check firewall rules
  • Verify the Jira Server URL is correct (include protocol: https://)

Tool Errors

  • Check that the issue key format is correct (e.g., PROJ-123)
  • Verify project keys exist and are accessible
  • Ensure you have the required permissions in Jira

Build Errors

# Clean rebuild
rm -rf dist node_modules
npm install
npm run build

Security Considerations

  • Never commit .env files - they contain sensitive credentials
  • Use strong passwords or personal access tokens
  • Enable SSL/TLS (JIRA_STRICT_SSL=true) in production
  • Limit Jira user permissions to what's necessary
  • Consider using a dedicated service account for API access

Jira Server vs Jira Cloud

This MCP server is designed for Jira Server/Data Center (on-premise installations). For Jira Cloud, you would need:

  • Different authentication (email + API token instead of username/password)
  • Different API endpoints (v3 instead of v2)
  • Account IDs instead of usernames

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues and questions:

Acknowledgments

Version History

1.0.0 (Initial Release)

  • Complete Jira Server integration
  • 20+ tools for issue management, workflow, and Agile operations
  • Support for JQL search
  • User and project management
  • Comprehensive error handling