MCP Server for Jira and Confluence

A Model Context Protocol (MCP) server that integrates with Atlassian's Jira and Confluence, enabling AI assistants to interact with these tools directly.

Features

• 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

• 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

Installation

1. Clone the repository
2. Install dependencies using uv:

pip install uv
uv pip install -e .

Configuration

Environment Variables

Set the following environment variables to configure the server:

Jira Configuration

• JIRA_URL: Base URL of your Jira instance (e.g., https://yourcompany.atlassian.net)
• JIRA_USERNAME: Your Jira username/email
• JIRA_API_TOKEN: Your Jira API token or password
• JIRA_PERSONAL_TOKEN: Personal access token (alternative to username/API token)

Confluence Configuration

• CONFLUENCE_URL: Base URL of your Confluence instance (e.g., https://yourcompany.atlassian.net/wiki)
• CONFLUENCE_USERNAME: Your Confluence username/email
• CONFLUENCE_API_TOKEN: Your Confluence API token or password
• CONFLUENCE_PERSONAL_TOKEN: Personal access token (alternative to username/API token)

Quick Setup

1. Create API tokens from your Atlassian account settings
2. 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"

3. Or use the provided run.sh script with environment variables

Usage

Starting the Server

Run the server directly:

python -m mcp_jira_confluence.server

VSCode MCP Extension

If using with the VSCode MCP extension, the server is automatically configured via .vscode/mcp.json.

Claude Desktop

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

"mcpServers": {
  "mcp-jira-confluence": {
    "command": "uv",
    "args": [
      "--directory",
      "/Users/annmariyajoshy/vibecoding/mcp-jira-confluence",
      "run",
      "mcp-jira-confluence"
    ]
    }
  }

"mcpServers": {
  "mcp-jira-confluence": {
    "command": "uvx",
    "args": [
      "mcp-jira-confluence"
    ]
  }
}

Resources

The server exposes the following types of resources:

• jira://issue/{ISSUE_KEY} - Jira issues
• confluence://page/{PAGE_ID} - Confluence pages
• confluence://space/{SPACE_KEY}/page/{PAGE_ID} - Confluence pages with space key

Usage

Available Tools

Jira Tools

• create-jira-issue: Create a new Jira issue
• comment-jira-issue: Add a comment to an issue
• transition-jira-issue: Change an issue's status
• get-jira-issue: Get detailed information about a specific Jira issue
• get-my-assigned-issues: Get issues assigned to you, ordered by priority and date
• summarize-jira-issue: Get comprehensive issue summary with comments and history
• extract-confluence-links: Find all Confluence and Git repository links in an issue

Confluence Tools

• create-confluence-page: Create a new Confluence page
• update-confluence-page: Update an existing page (version auto-fetched if not provided)
• comment-confluence-page: Add a comment to a page
• get-confluence-page: Get a specific page with optional comments/history
• search-confluence: Search pages using CQL queries
• ask-confluence-page: Ask questions about page content

Usage Examples

Getting Your Assigned Issues

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

Getting a Specific Jira Issue

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

Summarizing a Jira Issue

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.

Extracting Links from Issues

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)

Getting a Confluence Page

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

Searching Confluence Pages

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.

Asking Questions About Pages

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"

Common CQL Query Examples

• 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.

Available Prompts

AI-Powered Analysis

• summarize-jira-issue: Create a summary of a Jira issue
• create-jira-description: Generate a structured issue description
• summarize-confluence-page: Create a summary of a Confluence page
• create-confluence-content: Generate structured Confluence content
• answer-confluence-question: Answer questions about specific page content

Context Types for Question Answering

• summary: Quick answers using first 1000-1500 characters
• details: Comprehensive answers using full page content
• specific: Full content with enhanced filtering (future feature)

For detailed Confluence tool documentation and advanced CQL examples, see CONFLUENCE_TOOLS.md.

Practical Examples

Workflow: Research and Documentation

1. Search for relevant pages: Use search-confluence to find pages related to your topic
2. Get page details: Use get-confluence-page to retrieve full content with comments
3. Ask specific questions: Use ask-confluence-page to extract specific information
4. Create summaries: Use summarize-confluence-page prompt for quick overviews

Common Use Cases

Finding Documentation

"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')"

Getting Page Information

"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

Content Analysis

"What authentication methods are supported according to the API documentation?"
→ Use ask-confluence-page with the API doc page ID and your specific question

Knowledge Extraction

"Summarize the key points from the deployment guide"
→ Use summarize-confluence-page prompt with the deployment guide page ID

Development

Building and Publishing

To prepare the package for distribution:

1. Sync dependencies and update lockfile:

uv sync

2. Build package distributions:

uv build

This will create source and wheel distributions in the dist/ directory.

3. Publish to PyPI:

uv publish

Note: You'll need to set PyPI credentials via environment variables or command flags:

• Token: --token or UV_PUBLISH_TOKEN
• Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

Debugging

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-confluence

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.

Changelog

Version 0.2.4 (2025-07-27)

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

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

Version 0.2.3 (2025-07-27)

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)

Version 0.2.2 (2025-07-27)

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

Version 0.2.1 (2025-07-27)

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

Version 0.2.0 (2025-07-27)

Major Improvements:

• Fixed EmbeddedResource validation errors - All tools now use the correct MCP structure with type: "resource" and proper TextResourceContents format
• 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
• Fixed HTTP 409 conflicts - Made version parameter optional in update-confluence-page with automatic version fetching
• Added missing Confluence tools - Implemented get-confluence-page and search-confluence-pages with 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

Version 0.1.9 (2025-07-26)

• Initial PyPI release with basic Jira and Confluence functionality
• Fixed basic EmbeddedResource structure issues
• Added core tool implementations