mcp-atlassian

nanyang12138/mcp-atlassian

3.1

If you are the rightful owner of mcp-atlassian 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.

MCP server for Atlassian tools (Confluence, Jira) provides a seamless integration and management solution for Atlassian products using the Model Context Protocol.

MCP Atlassian

Model Context Protocol (MCP) server for Atlassian Cloud products (Confluence and Jira). This integration is designed specifically for Atlassian Cloud instances and does not support Atlassian Server or Data Center deployments.

Feature Demo

Demo

Resources

  • confluence://{space_key}: Access Confluence spaces and pages
  • confluence://{space_key}/pages/{title}: Access specific Confluence pages
  • jira://{project_key}: Access Jira project and its issues
  • jira://{project_key}/issues/{issue_key}: Access specific Jira issues

Tools

Confluence Tools

  1. confluence_search

    • Search Confluence content using CQL
    • Inputs:
      • query (string): CQL query string (e.g. 'type=page AND space=DEV')
      • limit (number, optional): Results limit (1-50, default: 10)
    • Returns: Array of search results with page_id, title, space, url, last_modified, type, and excerpt

  2. confluence_get_page

    • Get content of a specific Confluence page by ID
    • Inputs:
      • page_id (string): Confluence page ID
      • include_metadata (boolean, optional): Include page metadata (default: true)
    • Returns: Page content and optional metadata

  3. confluence_get_page_by_title

    • Get content of a Confluence page by space key and title
    • Inputs:
      • space_key (string): Confluence space key
      • title (string): Page title
    • Returns: Page content and metadata

  4. confluence_get_comments

    • Get comments for a specific Confluence page
    • Input:
      • page_id (string): Confluence page ID
    • Returns: Array of comments with author, creation date, and content

  5. confluence_list_spaces

    • List all available Confluence spaces
    • Inputs:
      • limit (number, optional): Maximum number of spaces to return (1-100, default: 25)
    • Returns: Array of spaces with key, name, and description

  6. confluence_get_space_pages

    • Get all pages from a specific Confluence space
    • Inputs:
      • space_key (string): Confluence space key
      • limit (number, optional): Maximum number of pages to return (1-100, default: 25)
    • Returns: Array of pages with page_id, title, url, and version

  7. confluence_get_page_children

    • Get child pages of a specific Confluence page
    • Inputs:
      • page_id (string): Parent page ID
      • limit (number, optional): Maximum number of children to return (1-100, default: 25)
    • Returns: Array of child pages with page_id, title, url, and parent_id

  8. confluence_create_page

    • Create a new Confluence page
    • Inputs:
      • space_key (string): Space key where page will be created
      • title (string): Page title
      • body (string): Page content in Confluence storage format
      • parent_id (string, optional): Parent page ID
    • Returns: Created page content and metadata

  9. confluence_update_page

    • Update an existing Confluence page
    • Inputs:
      • page_id (string): Page ID to update
      • title (string): New page title
      • body (string): New page content in Confluence storage format
      • version (number): Current page version number
    • Returns: Updated page content and metadata
Jira Tools

  1. jira_get_issue

    • Get details of a specific Jira issue
    • Inputs:
      • issue_key (string): Jira issue key (e.g., 'PROJ-123')
      • expand (string, optional): Fields to expand
    • Returns: Issue details including content and metadata

  2. jira_search

    • Search Jira issues using JQL
    • Inputs:
      • jql (string): JQL query string
      • fields (string, optional): Comma-separated fields (default: "*all")
      • limit (number, optional): Results limit (1-50, default: 10)
    • Returns: Array of matching issues with metadata

  3. jira_get_project_issues

    • Get all issues for a specific Jira project
    • Inputs:
      • project_key (string): Project key
      • limit (number, optional): Results limit (1-50, default: 10)
    • Returns: Array of project issues with metadata

  4. jira_get_projects

    • Get all accessible Jira projects
    • Returns: Array of all projects accessible to the authenticated user

  5. jira_get_issue_comments

    • Get comments for a specific Jira issue
    • Inputs:
      • issue_key (string): Jira issue key (e.g., 'PROJ-123')
    • Returns: Array of comments with author, creation date, and content

  6. jira_get_transitions

    • Get available status transitions for an issue
    • Inputs:
      • issue_key (string): Jira issue key (e.g., 'PROJ-123')
    • Returns: Array of available transitions with id and name

  7. jira_get_board_issues

    • Get issues from a specific Agile board
    • Inputs:
      • board_id (number): Board ID
      • limit (number, optional): Maximum number of results (1-50, default: 50)
    • Returns: Array of board issues with key, title, type, status, and link

  8. jira_create_issue

    • Create a new Jira issue
    • Inputs:
      • project_key (string): Project key
      • summary (string): Issue summary/title
      • issue_type (string): Issue type (e.g., 'Bug', 'Task', 'Story')
      • description (string, optional): Issue description
      • priority (string, optional): Priority name
      • assignee (string, optional): Assignee account ID
      • labels (array, optional): Array of label strings
    • Returns: Created issue content and metadata

  9. jira_update_issue

    • Update an existing Jira issue
    • Inputs:
      • issue_key (string): Issue key to update
      • summary (string, optional): New summary
      • description (string, optional): New description
      • priority (string, optional): New priority
      • assignee (string, optional): New assignee account ID
      • labels (array, optional): New labels
    • Returns: Updated issue content and metadata

  10. jira_add_comment

    • Add a comment to a Jira issue
    • Inputs:
      • issue_key (string): Issue key
      • comment (string): Comment text
    • Returns: Added comment details

  11. jira_transition_issue

    • Transition a Jira issue to a new status
    • Inputs:
      • issue_key (string): Issue key
      • transition_id (string): Transition ID
    • Returns: Transition result

Installation

Prerequisites

  • Python 3.10 or higher
  • uv (recommended) or pip

Using uv (Recommended)

  1. Clone the Repository:

    git clone https://github.com/nanyang12138/mcp-atlassian.git
cd mcp-atlassian

  2. Install with uv:

    uv pip install -e .

Using pip

  1. Clone the Repository:

    git clone https://github.com/nanyang12138/mcp-atlassian.git
cd mcp-atlassian

  2. Create Virtual Environment:

    python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

  3. Install Dependencies:

    pip install -e .

Configuration

The MCP Atlassian integration supports using either Confluence, Jira, or both services. You only need to provide the environment variables for the service(s) you want to use.

Usage with Claude Desktop

  1. Get API tokens from: https://id.atlassian.com/manage-profile/security/api-tokens

  2. Add to your claude_desktop_config.json with only the services you need:

For Confluence only:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-atlassian",
        "run",
        "mcp-atlassian"
      ],
      "env": {
        "CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@domain.com",
        "CONFLUENCE_API_TOKEN": "your_api_token"
      }
    }
  }
}

For Jira only:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-atlassian",
        "run",
        "mcp-atlassian"
      ],
      "env": {
        "JIRA_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your.email@domain.com",
        "JIRA_API_TOKEN": "your_api_token"
      }
    }
  }
}

For both services:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-atlassian",
        "run",
        "mcp-atlassian"
      ],
      "env": {
        "CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@domain.com",
        "CONFLUENCE_API_TOKEN": "your_api_token",
        "JIRA_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your.email@domain.com",
        "JIRA_API_TOKEN": "your_api_token"
      }
    }
  }
}

Alternative: Using Python directly (if not using uv):

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "python",
      "args": ["-m", "mcp_atlassian.server"],
      "env": {
        "CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@domain.com",
        "CONFLUENCE_API_TOKEN": "your_api_token",
        "JIRA_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your.email@domain.com",
        "JIRA_API_TOKEN": "your_api_token"
      }
    }
  }
}

Usage with Cline

Add to your MCP settings in Cline. There are two methods:

Method 1: Using Python directly (recommended for development)

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "/path/to/mcp-atlassian/.venv/bin/python",
      "args": [
        "-m",
        "mcp_atlassian.server"
      ],
      "env": {
        "CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@domain.com",
        "CONFLUENCE_API_TOKEN": "your_api_token",
        "JIRA_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your.email@domain.com",
        "JIRA_API_TOKEN": "your_api_token"
      }
    }
  }
}

Method 2: Using the entry point (requires package installation)

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-atlassian",
        "run",
        "mcp-atlassian"
      ],
      "env": {
        "CONFLUENCE_URL": "https://your-domain.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@domain.com",
        "CONFLUENCE_API_TOKEN": "your_api_token",
        "JIRA_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your.email@domain.com",
        "JIRA_API_TOKEN": "your_api_token"
      }
    }
  }
}

Debugging

You can use the MCP inspector to debug the server:

npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-atlassian run mcp-atlassian

Or if using Python directly:

npx @modelcontextprotocol/inspector python -m mcp_atlassian.server

View logs with:

  • macOS: tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
  • Windows: Check %APPDATA%\Claude\logs\
  • Linux: Check ~/.config/Claude/logs/

Development

Running Tests

uv run pytest

Code Formatting

uv run ruff format .

Type Checking

uv run mypy src/

Security

  • Never share API tokens
  • Keep .env files secure and private
  • Use API tokens with minimal required permissions
  • Regularly rotate your API tokens
  • See for best practices

Dependencies

  • atlassian-python-api>=3.41.16 - Atlassian API client
  • beautifulsoup4>=4.12.3 - HTML parsing
  • httpx>=0.28.0 - HTTP client
  • mcp>=1.0.0 - Model Context Protocol SDK
  • python-dotenv>=1.0.1 - Environment variable management
  • markdownify>=0.11.6 - HTML to Markdown conversion

License

Licensed under MIT - see file. This is not an official Atlassian product.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Note: This is a fork of the original mcp-atlassian repository.