A Model Context Protocol (MCP) server that integrates with Atlassian's Jira and Confluence, enabling AI assistants to interact with these tools directly.
-
Jira Integration
- List recent issues
- View issue details including comments
- Create new issues
- Add comments to issues
- Transition issues between statuses
- Get assigned issues - Retrieve your assigned tickets ordered by priority and date
- Summarize issues - Get comprehensive issue summaries with comments and history
- Extract Confluence and Git links - Find all Confluence page references and Git repository URLs in issues
- Agile/Scrum Support - Board management, sprint tracking, daily standup summaries
- AI-Powered Assistance - Smart task assignment recommendations and story point estimation
-
Confluence Integration
- List recent pages
- View page content
- Create new pages
- Update existing pages
- Add comments to pages
- Search pages using CQL (Confluence Query Language)
- Get specific pages by ID or title
- Ask questions about page content
-
AI-Powered Prompts
- Summarize Jira issues
- Create structured Jira issue descriptions
- Summarize Confluence pages
- Generate structured Confluence content
- Clone the repository
- Install dependencies using
uv:
pip install uv
uv pip install -e .Set the following environment variables to configure the server:
JIRA_URL: Base URL of your Jira instance (e.g.,https://yourcompany.atlassian.net)JIRA_USERNAME: Your Jira username/emailJIRA_API_TOKEN: Your Jira API token or passwordJIRA_PERSONAL_TOKEN: Personal access token (alternative to username/API token)
CONFLUENCE_URL: Base URL of your Confluence instance (e.g.,https://yourcompany.atlassian.net/wiki)CONFLUENCE_USERNAME: Your Confluence username/emailCONFLUENCE_API_TOKEN: Your Confluence API token or passwordCONFLUENCE_PERSONAL_TOKEN: Personal access token (alternative to username/API token)
- Create API tokens from your Atlassian account settings
- Set environment variables in your shell:
export JIRA_URL="https://yourcompany.atlassian.net"
export JIRA_USERNAME="your-email@company.com"
export JIRA_API_TOKEN="your-jira-api-token"
export CONFLUENCE_URL="https://yourcompany.atlassian.net/wiki"
export CONFLUENCE_USERNAME="your-email@company.com"
export CONFLUENCE_API_TOKEN="your-confluence-api-token"- Or use the provided
run.shscript with environment variables
Run the server directly:
python -m mcp_jira_confluence.serverIf using with the VSCode MCP extension, the server is automatically configured via .vscode/mcp.json.
To use with Claude Desktop, add the following configuration:
On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%/Claude/claude_desktop_config.json
Development/Unpublished Servers Configuration
"mcpServers": {
"mcp-jira-confluence": {
"command": "uv",
"args": [
"--directory",
"/Users/annmariyajoshy/vibecoding/mcp-jira-confluence",
"run",
"mcp-jira-confluence"
]
}
}Published Servers Configuration
"mcpServers": {
"mcp-jira-confluence": {
"command": "uvx",
"args": [
"mcp-jira-confluence"
]
}
}The server exposes the following types of resources:
jira://issue/{ISSUE_KEY}- Jira issuesconfluence://page/{PAGE_ID}- Confluence pagesconfluence://space/{SPACE_KEY}/page/{PAGE_ID}- Confluence pages with space key
create-jira-issue: Create a new Jira issuecomment-jira-issue: Add a comment to an issuetransition-jira-issue: Change an issue's status (supports transition names like "In Progress", "Done")get-jira-transitions: Get available transitions for an issueget-jira-issue: Get detailed information about a specific Jira issueget-my-assigned-issues: Get issues assigned to you, ordered by priority and datesummarize-jira-issue: Get comprehensive issue summary with comments and historyextract-confluence-links: Find all Confluence and Git repository links in an issue
get-agile-boards: Get all agile boards or filter by project - essential for scrum mastersget-board-sprints: Get sprints for a specific board (active, closed, future, or all)get-daily-standup-summary: Comprehensive daily standup report with sprint progress, team status, and blockersget-task-assignment-recommendations: AI-powered assignment suggestions based on historical data and expertiseestimate-story-points: AI-powered story point estimation using complexity analysis and historical patterns
create-confluence-page: Create a new Confluence pageupdate-confluence-page: Update an existing page (version auto-fetched if not provided)comment-confluence-page: Add a comment to a pageget-confluence-page: Get a specific page with optional comments/historysearch-confluence: Search pages using CQL queriesask-confluence-page: Ask questions about page content
Get issues assigned to you ordered by priority (highest first) and creation date (newest first):
Default (25 issues, exclude completed):
- No parameters needed
Custom parameters:
- max_results: 50 (max: 100)
- include_done: true (includes closed/resolved issues)
The tool returns issues with:
- Issue key, summary, status, priority
- Issue type, creation date, due date
- Formatted for easy reading
Get detailed information about any Jira issue by its key:
Basic issue info:
- issue_key: "PROJ-123" (required)
- include_comments: false (default)
With comments:
- issue_key: "PROJ-123"
- include_comments: true (includes last 3 comments)
Returns:
- Complete issue details (status, priority, assignee, dates)
- Full description
- Optional recent comments
- Formatted for easy reading
Get comprehensive issue information including:
- Basic details (status, priority, assignee, dates)
- Full description
- Recent comments (last 5)
- Confluence page references
- Status history
Parameters:
- issue_key: "PROJ-123" (required)
Returns formatted markdown summary perfect for AI analysis.
Change an issue's status using human-readable transition names:
Using transition name (recommended):
- issue_key: "PROJ-123"
- transition_name: "In Progress" // or "Done", "To Do", etc.
Using transition ID (advanced):
- issue_key: "PROJ-123"
- transition_id: "21"
The tool automatically:
- Finds the correct transition ID from the name
- Provides helpful error messages with available options
- Shows the new status after transition
Common transition names: "To Do", "In Progress", "Done", "Closed"
See what status changes are possible for an issue:
Parameters:
- issue_key: "PROJ-123" (required)
Returns:
- List of available transitions with names and target statuses
- Transition IDs for advanced usage
- Usage examples for each transition
- Clear formatting for easy reading
Use this before transitioning to see available options.
Find all Confluence and Git repository links in a Jira issue from:
- Issue description text
- Comments from all users
- Remote links attached to the issue
Parameters:
- issue_key: "PROJ-123" (required)
- include_git_urls: true (default, set to false to exclude Git links)
Supported Git platforms:
- GitHub, GitLab, Bitbucket (cloud and self-hosted)
- Azure DevOps / Visual Studio Team Services
- Generic Git hosting platforms
- SSH Git URLs (git@server:org/repo.git)
Returns:
- Confluence page links with titles and context
- Git repository URLs with source location
- Organized by category (Confluence vs Git)
- Source information (description, comment, remote link)
Get all agile boards or filter by project:
All boards:
- No parameters needed
Project-specific boards:
- project_key: "PROJ" (optional filter)
Returns:
- Board ID, name, type (Scrum/Kanban)
- Associated project information
- Essential for scrum masters managing multiple teams
Get sprints for a specific agile board:
Active sprints only (default):
- board_id: "123" (required)
All sprint states:
- board_id: "123"
- state: "all" (options: "active", "closed", "future", "all")
Returns:
- Sprint ID, name, state, dates
- Sprint goals and progress information
- Perfect for sprint planning and retrospectives
Get comprehensive daily standup report for active sprint:
Parameters:
- board_id: "123" (required - get from get-agile-boards)
Returns detailed analysis:
- Sprint progress (issues & story points completion %)
- Status breakdown (To Do, In Progress, Done, etc.)
- Team member workload and current tasks
- Potential blockers (high priority unresolved issues)
- In-progress tasks by assignee
- Key metrics for standup discussion
Perfect for scrum masters to quickly assess sprint health!
Get smart recommendations for who should work on a task:
Parameters:
- issue_key: "PROJ-123" (required)
AI analyzes:
- Historical data from similar resolved issues
- Team member expertise in components/labels
- Current workload of potential assignees
- Average resolution times for similar work
- Component and technology experience
Returns:
- Ranked list of recommended assignees
- Confidence scores and reasoning
- Current workload information
- Historical performance data
Get intelligent story point estimates based on complexity and history:
Parameters:
- issue_key: "PROJ-123" (required)
AI analyzes:
- Issue complexity (description length, components, labels)
- Historical data from similar resolved issues
- Story point patterns in your project
- Component and issue type complexity
Returns:
- Primary recommendation with confidence level
- Alternative estimates for team discussion
- Complexity analysis breakdown
- Similar issues for reference
- Historical patterns and distribution
Perfect for sprint planning and effort estimation!
You can retrieve a page using either its ID or title + space key:
By ID:
- page_id: "123456789"
- include_comments: true
- include_history: false
By title and space:
- title: "API Documentation"
- space_key: "DEV"
- include_comments: false
Search using CQL (Confluence Query Language):
Simple text search:
- query: "API Documentation"
- max_results: 10
Search by title:
- query: "title ~ 'API Documentation'"
- max_results: 10
Search in specific space:
- query: "space.key = 'DEV'"
- space_key: "DEV"
- max_results: 5
Recent pages:
- query: "lastmodified >= now('-7d')"
Note: The system automatically adds "type = page" to queries that don't specify a content type.
Ask specific questions about page content:
- page_id: "123456789"
- question: "What are the main features described?"
- context_type: "summary" | "details" | "specific"
Or using title + space:
- title: "User Guide"
- space_key: "DOCS"
- question: "How do I configure authentication?"
- context_type: "details"
- Simple text search:
"API Documentation"(searches in content and title) - Search by title:
title ~ "API Documentation" - Search in space:
space.key = "DEV" - Recent pages:
lastmodified >= now("-7d") - By author:
creator = "john.doe" - Combined:
title ~ "API" AND space.key = "DEV" AND lastmodified >= now("-30d") - Text in content:
text ~ "authentication method"
Note: All queries automatically include type = page unless explicitly specified otherwise.
summarize-jira-issue: Create a summary of a Jira issuecreate-jira-description: Generate a structured issue descriptionsummarize-confluence-page: Create a summary of a Confluence pagecreate-confluence-content: Generate structured Confluence contentanswer-confluence-question: Answer questions about specific page content
summary: Quick answers using first 1000-1500 charactersdetails: Comprehensive answers using full page contentspecific: Full content with enhanced filtering (future feature)
For detailed Confluence tool documentation and advanced CQL examples, see CONFLUENCE_TOOLS.md.
- Search for relevant pages: Use
search-confluenceto find pages related to your topic - Get page details: Use
get-confluence-pageto retrieve full content with comments - Ask specific questions: Use
ask-confluence-pageto extract specific information - Create summaries: Use
summarize-confluence-pageprompt for quick overviews
"Search for all API documentation in the DEV space that was updated in the last month"
→ Use search-confluence with query: "type = page AND space.key = 'DEV' AND title ~ 'API' AND lastmodified >= now('-30d')"
"Get the User Guide page from DOCS space with all comments"
→ Use get-confluence-page with title: "User Guide", space_key: "DOCS", include_comments: true
"What authentication methods are supported according to the API documentation?"
→ Use ask-confluence-page with the API doc page ID and your specific question
"Summarize the key points from the deployment guide"
→ Use summarize-confluence-page prompt with the deployment guide page ID
To prepare the package for distribution:
- Sync dependencies and update lockfile:
uv sync- Build package distributions:
uv buildThis will create source and wheel distributions in the dist/ directory.
- Publish to PyPI:
uv publishNote: You'll need to set PyPI credentials via environment variables or command flags:
- Token:
--tokenorUV_PUBLISH_TOKEN - Or username/password:
--username/UV_PUBLISH_USERNAMEand--password/UV_PUBLISH_PASSWORD
Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.
You can launch the MCP Inspector via npm with this command:
npx @modelcontextprotocol/inspector uv --directory /Users/annmariyajoshy/vibecoding/mcp-jira-confluence run mcp-jira-confluenceUpon launching, the Inspector will display a URL that you can access in your browser to begin debugging.
Critical Bug Fix - Daily Standup Summary:
- 🐛 Fixed NoneType Error - Resolved "NoneType object has no attribute 'get'" error in daily standup summary:
- Enhanced null checking: Added comprehensive null checks for all API responses (sprints, issues, nested objects)
- Safe object access: Implemented safe access patterns for nested objects (status, assignee, priority, issuetype)
- Better error handling: Added type checking for dictionaries and lists throughout the analysis
- Improved debugging: Added traceback logging for better error diagnosis
- Robust data validation: Validate sprint data, issue data, and all nested structures before processing
- Graceful degradation: Return meaningful error messages instead of crashing on invalid data
Technical Improvements:
- Added defensive programming patterns for all data access in daily standup analysis
- Enhanced error messages with specific context about what data is missing or invalid
- Improved logging with full traceback information for debugging
- Better handling of edge cases (empty responses, malformed data, missing fields)
Critical Agile API Fixes:
- 🔧 Fixed Jira Agile API Endpoints - Resolved 404 errors with legacy Jira instances:
- Corrected greenhopper URLs: Fixed
/rest/api/2/greenhopper/1.0/rapidview→/rest/greenhopper/1.0/rapidviews/list - Added sprint query endpoint: Implemented
/rest/greenhopper/1.0/sprintquery/{board_id}for legacy Jira - Enhanced API fallbacks: Better error handling with graceful degradation from modern to legacy APIs
- Direct session calls: Improved control over HTTP requests for agile endpoints
- JQL fallback: Added JQL search fallback for sprint issues when agile API unavailable
- Response normalization: Convert legacy API responses to modern format for consistency
- Corrected greenhopper URLs: Fixed
Technical Improvements:
- Fixed argument validation in server.py to allow empty parameters for some tools
- Enhanced error messages with specific API endpoint information
- Added comprehensive API documentation (AGILE_API_FIX.md)
- Better compatibility with both Jira Cloud and Server instances
- Improved debugging information for API endpoint issues
Major Agile/Scrum Features:
- 🏃♂️ Complete Agile/Scrum Toolset - Full suite of tools for scrum masters and agile teams:
get-agile-boards- Get all agile boards or filter by project with board types and project infoget-board-sprints- Get sprints for any board (active, closed, future, or all) with goals and datesget-daily-standup-summary- Comprehensive daily standup reports for scrum masters with:- Sprint progress metrics (issues & story points completion %)
- Team status breakdown with current workloads
- Potential blockers identification
- In-progress tasks by assignee
get-task-assignment-recommendations- AI-powered assignment suggestions using:- Historical data from similar resolved issues
- Team member expertise analysis
- Current workload considerations
- Component and technology experience
estimate-story-points- AI-powered story point estimation using:- Complexity analysis (description, components, labels)
- Historical patterns from similar issues
- Confidence scoring and alternatives
- Reference to most similar resolved issues
Technical Enhancements:
- Added comprehensive agile API support with fallback to greenhopper for older Jira versions
- Implemented sophisticated AI analysis algorithms for assignment and estimation
- Enhanced error handling for cases with no active sprints or insufficient data
- Rich markdown formatting for all agile tool outputs
- Embedded resource support for better MCP integration
Enhanced Jira Transitions:
-
Enhanced
transition-jira-issue- Now supports transition by name instead of cryptic IDs:- Human-readable transitions - Use "In Progress", "Done", "To Do" instead of numeric IDs
- Automatic ID resolution - Finds the correct transition ID from user-friendly names
- Smart matching - Matches both transition names and target status names
- Helpful error messages - Shows available transitions when invalid names are used
- Backwards compatibility - Still supports transition_id parameter for advanced users
-
New
get-jira-transitionstool - Discover available transitions for any issue:- Complete transition list - Shows all possible status changes for an issue
- Rich information - Displays transition names, target statuses, and IDs
- Usage guidance - Provides examples for using each transition
- User-friendly format - Clear markdown formatting for easy reading
Technical Improvements:
- Added
transition_issue_by_name()method with intelligent transition matching - Enhanced error handling with available transitions in error messages
- Case-insensitive transition name matching for better user experience
- Updated tool schemas to support both name and ID parameters
- Comprehensive validation and helpful error messages
Enhanced Confluence Search:
- Smart CQL Query Builder - Automatically enhances simple search queries with proper CQL syntax:
- Simple text queries - "API docs" becomes
(title ~ "API docs" OR text ~ "API docs") - Phrase detection - Longer queries become
text ~ "your search phrase" - Advanced CQL preservation - Complex queries with operators (AND, OR, ~, =) are used as-is
- Space integration - Automatically adds space constraints when specified
- Query transparency - Shows the enhanced CQL query in search results
- Simple text queries - "API docs" becomes
Technical Improvements:
- Added
build_smart_cql_query()function for intelligent query enhancement - Enhanced search-confluence tool description to explain automatic query enhancement
- Better user experience with query transformation visibility
- Improved search accuracy for both novice and advanced users
Enhanced Link Extraction:
- Enhanced
extract-confluence-links- Now extracts both Confluence pages AND Git repository URLs:- Git Repository Support - Detects URLs from GitHub, GitLab, Bitbucket, Azure DevOps, and other Git platforms
- Smart Pattern Matching - Uses regex patterns to identify repository URLs in issue descriptions, comments, and remote links
- Comprehensive Coverage - Scans all issue text fields for both Confluence and Git references
- Rich Output - Returns organized lists of both Confluence pages and Git repositories with context
Technical Improvements:
- Added
_extract_git_urls_from_text()method with support for major Git platforms - Enhanced URL extraction patterns for better accuracy
- Improved tool description and documentation
- Better organization of extracted links by type (Confluence vs Git)
New Jira Tools:
get-my-assigned-issues- Get issues assigned to you ordered by priority (highest first) and creation date (newest first)- Configurable max results (default: 25, max: 100)
- Option to include completed/closed issues
- Rich formatting with status, priority, type, dates
summarize-jira-issue- Comprehensive issue analysis including:- Complete issue details (status, priority, assignee, dates)
- Full description and recent comments (last 5)
- Confluence page references from remote links
- Formatted as markdown for easy AI processing
extract-confluence-links- Find all Confluence page references in issues:- Scans issue description, all comments, and remote links
- Supports multiple Confluence URL patterns (atlassian.net, custom domains)
- Returns link titles, URLs, and source context
Technical Enhancements:
- Added
get_current_user()API method for user context - Enhanced JQL queries with proper field selection and ordering
- Robust URL extraction with regex pattern matching
- Improved error handling for missing or invalid issues
- Better date formatting for human readability
Formatting Fixes:
- Fixed 400 Bad Request errors with complex markdown formatting in Confluence pages
- Implemented intelligent complexity detection - automatically chooses conversion strategy
- Added robust error handling with graceful fallbacks for conversion failures
- Enhanced list processing with proper HTML grouping and nesting
Major Improvements:
- Fixed EmbeddedResource validation errors - All tools now use the correct MCP structure with
type: "resource"and properTextResourceContentsformat - Enhanced Confluence formatting - Dramatically improved markdown to Confluence conversion:
- Proper list handling (grouped
<ul>/<ol>tags instead of individual ones) - Better code block formatting with language support
- Improved inline formatting (bold, italic, code, links)
- Smarter paragraph handling
- More robust markdown detection patterns
- Proper list handling (grouped
- Fixed HTTP 409 conflicts - Made version parameter optional in
update-confluence-pagewith automatic version fetching - Added missing Confluence tools - Implemented
get-confluence-pageandsearch-confluence-pageswith proper CQL support - Improved error handling - Better error messages and validation throughout
Technical Changes:
- Rewrote
ConfluenceFormatter.markdown_to_confluence()with line-by-line processing - Added regex-based markdown detection with multiple pattern matching
- Enhanced
_process_inline_formatting()helper for consistent formatting - Improved version conflict resolution in page updates
- Added comprehensive logging for format detection and conversion
- Initial PyPI release with basic Jira and Confluence functionality
- Fixed basic EmbeddedResource structure issues
- Added core tool implementations