jira-mcp-server

akworob/jira-mcp-server

3.2

If you are the rightful owner of jira-mcp-server 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 JIRA that enables natural language interactions with your JIRA instance.

Tools
5
Resources
0
Prompts
0

JIRA MCP Server

A Model Context Protocol (MCP) server for JIRA that enables natural language interactions with your JIRA instance. Query user progress, search stories, analyze sprints, and track team velocity through conversational AI.

Features

Core Tools

  1. jira_search_issues - Search for JIRA issues with flexible filters

    • JQL query support for advanced searches
    • Filter by project, assignee, status, type, sprint
    • Text search in summaries and descriptions
    • Date-based filtering
    • Pagination support

  2. jira_get_user_progress - Get comprehensive user progress reports

    • Issues completed in specified time period
    • Currently in-progress work
    • Story points completed
    • Velocity calculations

  3. jira_get_project_info - Get project information and statistics

    • Project metadata and description
    • Issue counts by status and type
    • Recent activity summary
    • Completion rates

  4. jira_get_sprint_info - Get sprint information and progress

    • Active, closed, and future sprints
    • Issues in each sprint
    • Sprint goals and dates
    • Story point tracking

  5. jira_get_team_velocity - Calculate team velocity metrics

    • Average velocity across sprints
    • Sprint completion rates
    • Predictive capacity planning
    • Velocity trends

Installation

Prerequisites

Step 1: Clone and Setup

git clone https://github.com/yourusername/jira-mcp-server.git
cd jira-mcp-server

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Step 2: Configure Environment Variables

Copy the example environment file and fill in your credentials:

cp .env.example .env

Edit .env with your JIRA credentials:

JIRA_URL=https://yourcompany.atlassian.net
JIRA_EMAIL=your-email@company.com
JIRA_API_TOKEN=your-api-token-here

Step 2a: Test Connection (Optional but Recommended)

Verify your JIRA connection:

python test_connection.py

This will check your credentials and API access before configuring Claude Desktop.

Step 3: Configure Claude Desktop

Add the JIRA MCP server to your Claude Desktop configuration:

For macOS: Edit ~/Library/Application Support/Claude/claude_desktop_config.json For Windows: Edit %APPDATA%\Claude\claude_desktop_config.json For Linux: Edit ~/.config/claude/claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "jira": {
      "command": "/absolute/path/to/jira-mcp-server/venv/bin/python",
      "args": ["/absolute/path/to/jira-mcp-server/jira_mcp.py"],
      "env": {
        "JIRA_URL": "https://yourcompany.atlassian.net",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Note: Use absolute paths for both command and args. If you're using a virtual environment (recommended), point to the Python binary inside the venv.

Step 4: Restart Claude Desktop

After adding the configuration, restart Claude Desktop to load the MCP server.

Usage Examples

Once configured, you can ask Claude natural language questions about your JIRA data:

User Progress Queries

  • "What has John been working on this week?"
  • "Show me my completed stories from the last 30 days"
  • "How many story points did our team complete this sprint?"
  • "What's currently in progress for sarah@company.com?"

Project and Sprint Queries

  • "Give me an overview of project ABC"
  • "What are the active sprints for the mobile team?"
  • "Show me the sprint velocity for the last 5 sprints"
  • "How many bugs are open in project XYZ?"

Issue Searches

  • "Find all high-priority bugs assigned to me"
  • "Search for stories in the current sprint"
  • "Show me issues updated in the last 24 hours"
  • "Find all epics in project MOBILE"

Team Analytics

  • "Calculate our team's velocity over the last quarter"
  • "What's our sprint completion rate?"
  • "How many story points can we commit to next sprint?"
  • "Show me the burndown for the current sprint"

Advanced Usage

Using JQL Queries

The jira_search_issues tool supports full JQL syntax:

"Search using JQL: project = ABC AND status = 'In Progress' AND assignee = currentUser()"

Response Formats

All tools support both JSON and Markdown response formats:

  • Markdown (default): Human-readable format for conversations
  • JSON: Structured data for further processing

Pagination

The server automatically handles pagination for large result sets:

  • Automatic pagination: User progress, sprint info, and velocity queries automatically fetch all issues (up to reasonable limits)
  • Manual pagination: For jira_search_issues, use offset and limit parameters: 
    "Get the next 50 issues (offset: 50, limit: 50)"
  • Limits: To prevent performance issues, automatic pagination is limited to:
    • User progress: 500 completed issues, 200 in-progress, 200 todo
    • Sprint info: 500 issues per sprint
    • Team velocity: 500 issues per sprint

Configuration Options

Custom Field Mapping

The server uses customfield_10000 for story points by default. If your JIRA instance uses a different field:

  1. Find your story points field ID in JIRA
  2. Update the field references in the code

API Rate Limits

The server respects JIRA's API rate limits. For high-volume operations, consider:

  • Using pagination
  • Caching frequently accessed data
  • Implementing request throttling

Troubleshooting

Authentication Errors

  • Verify your JIRA_URL doesn't have trailing slashes
  • Ensure your API token is valid and not expired
  • Check that your email matches your JIRA account

Permission Issues

  • Ensure your account has read access to the projects you're querying
  • Some fields may require additional permissions

Field Not Found

  • Custom fields vary by JIRA instance
  • Check your instance's field configuration
  • Update field IDs in the code as needed

Connection Timeouts

  • Check your internet connection
  • Verify JIRA instance is accessible
  • Consider increasing timeout values in the code

Security Considerations

  1. API Token Storage: Never commit API tokens to version control
  2. Environment Variables: Use secure methods to manage environment variables
  3. Access Control: The server inherits permissions from the authenticated user
  4. Data Privacy: Be mindful of sensitive information in JIRA data

Extending the Server

To add new tools:

  1. Create a new Pydantic model for input validation
  2. Add a new @mcp.tool decorated function
  3. Implement the JIRA API interaction
  4. Add appropriate error handling
  5. Support both JSON and Markdown output formats

Example structure:

@mcp.tool(name="jira_new_tool")
async def jira_new_tool(params: NewToolInput) -> str:
    """Tool description"""
    # Implementation here
    pass

API Reference

Environment Variables

VariableDescriptionRequired
JIRA_URLYour JIRA instance URLYes
JIRA_EMAILYour JIRA account emailYes
JIRA_API_TOKENYour JIRA API tokenYes

Tool Parameters

Each tool accepts specific parameters. Use the tool descriptions in Claude for detailed parameter information.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Make your changes
  4. Test thoroughly using test_connection.py
  5. Commit your changes (git commit -m 'Add some AmazingFeature')
  6. Push to the branch (git push origin feature/AmazingFeature)
  7. Open a Pull Request

License

MIT License - see the file for details.

This MCP server is provided as-is for use with Claude and JIRA. Ensure compliance with your organization's policies regarding API usage and data access.

Support

For issues or questions:

  1. Check the troubleshooting section above
  2. Review JIRA API documentation
  3. Consult the MCP protocol documentation

Technical Details

JIRA API Version

This server uses JIRA REST API v3 (/rest/api/3/), ensuring compatibility with the latest Atlassian Cloud instances. The deprecated v2 API is not supported.

Automatic Pagination

The server automatically fetches all available results for:

  • User progress queries (with configurable limits)
  • Sprint issue retrieval
  • Team velocity calculations

This ensures you get complete data even when JIRA's API limit is 100 results per page.

Connection Testing

Use the included test_connection.py script to verify:

  • Environment variables are set correctly
  • JIRA credentials are valid
  • API access is working
  • Project permissions are correct
  • Agile/Scrum features are available

Version History

  • v1.1.0 - Enhanced pagination and API updates

    • Automatic pagination for all query types
    • Migration to JIRA API v3
    • Improved error handling
    • Connection testing script

  • v1.0.0 - Initial release with core JIRA tools

    • Issue search and filtering
    • User progress tracking
    • Project information
    • Sprint management
    • Team velocity calculations