Atlassian MCP server

This MCP server provides a standardized interface for AI agents to interact with Atlassian products, offering comprehensive tools for Confluence and Jira operations. It supports modern API integrations, extensive toolsets, and flexible configuration options.

Installation

Standard Installation

1. Clone the repository:

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

2. Install dependencies:

   npm install
   # or using make
   make install
   

3. Create a .env file in the root directory with your Atlassian credentials:

   ATLASSIAN_HOST=https://your-domain.atlassian.net
   ATLASSIAN_EMAIL=your-email@example.com
   ATLASSIAN_API_TOKEN=your-api-token
   

Docker Installation

1. Clone the repository:

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

2. Create a .env file as described above.

3. Build and run the Docker container:

   # Build the Docker image
   make docker-build
   
   # Run the Docker container
   make docker-run
   
   # Or use Docker Compose
   make docker-compose
   

Usage

Starting the Server

# Using npm
npm start

# Using make
make start

# Using Docker
make docker-run

This will start the MCP server, which will listen and respond on streamable HTTP.

MCP Configuration

{
  "mcp-searchapi": {
    "name": "mcp-searchapi",
    "type": "streamable-http",
    "streamable": true,
    "url": "http://localhost:3007/mcp"
  }
}

Available Tools

Confluence Tools

Search & Discovery:

• search_confluence: Search for content in Confluence using v1 API with CQL

  • Parameters: searchText (string), spaceKey (string, optional), limit (number), start (number)

• search_confluence_pages_by_title: Search pages by title using v2 API

  • Parameters: title (string, optional), spaceId (string, optional), limit (number), cursor (string, optional)

Space Management:

• get_confluence_space_by_id_or_key: Get information about a specific Confluence space

  • Parameters: spaceIdOrKey (string)

• get_confluence_spaces: Get all available spaces

  • Parameters: limit (number, optional), cursor (string, optional)

Page Management:

• get_confluence_content: Get specific page content by ID

  • Parameters: pageId (string), bodyFormat (enum: storage/atlas_doc_format/wiki, optional)

• get_confluence_pages: Get all pages in a space

  • Parameters: spaceId (string), limit (number, optional), cursor (string, optional)

• get_confluence_child_pages: Get child pages of a specific page

  • Parameters: pageId (string), limit (number, optional), cursor (string, optional)

• confluence_create_page: Create a new Confluence page

  • Parameters: spaceId (string), title (string), content (string), status (enum, optional), representation (enum, optional), parentId (string, optional)

• confluence_update_page: Update an existing page

  • Parameters: pageId (string), title (string), content (string), version (number), status (enum, optional), representation (enum, optional), versionMessage (string, optional)

• update_confluence_page_title: Update only the title of a page

  • Parameters: pageId (string), title (string), status (enum, optional)

• confluence_delete_page: Delete a Confluence page

  • Parameters: pageId (string)

Label Management:

• get_confluence_pages_by_label: Find pages with specific labels

  • Parameters: label (string), spaceId (string, optional), limit (number, optional), cursor (string, optional)

• get_confluence_page_labels: Get labels for a specific page

  • Parameters: pageId (string), limit (number, optional), cursor (string, optional)

• add_confluence_page_labels: Add labels to a page

  • Parameters: pageId (string), labels (array of strings)

Comments:

• get_confluence_page_comments: Get regular comments on a page

  • Parameters: pageId (string), limit (number, optional), cursor (string, optional)

• add_confluence_page_comment: Add a comment to a page

  • Parameters: pageId (string), content (string), representation (enum, optional)

• get_confluence_page_inline_comments: Get inline comments on a page

  • Parameters: pageId (string), limit (number, optional), cursor (string, optional)

• create_confluence_footer_comment: Create a footer comment

  • Parameters: pageId (string, optional), blogPostId (string, optional), parentCommentId (string, optional), attachmentId (string, optional), customContentId (string, optional), content (string), representation (enum, optional)

Jira Tools

• search_jira_issues: Search for issues using JQL (Jira Query Language)

  • Parameters: jql (string), maxResults (number, optional)

• get_jira_issue: Get detailed information about a specific issue

  • Parameters: issueKey (string)

• jira_get_all_projects: Get all accessible projects

  • Parameters: none

• jira_create_issue: Create a new Jira issue

  • Parameters: projectKey (string), issueType (string), summary (string), description (string, optional), additional fields

• jira_update_issue: Update an existing issue

  • Parameters: issueKey (string), fields (object with update data)

• jira_add_comment: Add a comment to an issue

  • Parameters: issueKey (string), comment (string)

• jira_get_transitions: Get available transitions for an issue

  • Parameters: issueKey (string)

• jira_transition_issue: Transition an issue to a different status

  • Parameters: issueKey (string), transitionId (string), comment (string, optional)

Confluence API Notes

This server primarily uses the Confluence v2 REST API for most operations, with strategic fallback to v1 API where necessary:

• v2 API: Used for spaces, pages, comments, labels - provides better performance and modern cursor-based pagination
• v1 API: Used for content search via CQL - provides more powerful search capabilities
• SSL Support: Configurable SSL verification bypass for self-hosted instances
• Authentication: Supports basic auth, OAuth 2.0 (planned), and PAT tokens

Security Features

• Read-Only Mode: Disable all write operations for safe exploration
• Tool Whitelist: Enable only specific tools via ENABLED_TOOLS environment variable
• PII Filtering: Automatic detection and masking of sensitive information in responses
• Error Context: Detailed error messages without exposing sensitive configuration

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "atlassian" '{"command":"npx","args":["-y","mcp-atlassian"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "atlassian": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-atlassian"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

{
    "mcpServers": {
        "atlassian": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-atlassian"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect