MCP Atlassian

A Model Context Protocol (MCP) server that provides comprehensive tools for interacting with Atlassian products (Confluence and Jira).

Overview

This MCP server allows AI agents to interact with Atlassian products through a standardized interface. It provides extensive tools for:

• Confluence: Full CRUD operations, content search, space management, page management, comments, labels, and more using v2 REST API

• Jira: Issue management, project operations, transitions, comments, and comprehensive workflow support

Related MCP server: MCP Atlassian Server

Key Features

• Modern API Support: Uses Confluence v2 REST API with fallback to v1 for search functionality

• Comprehensive Toolset: 18+ Confluence tools and 8+ Jira tools covering all major operations

• Security & Privacy: Built-in PII filtering and SSL verification controls

• Flexible Configuration: Support for separate service URLs, authentication methods, and tool filtering

• Pagination Support: Cursor-based pagination for v2 APIs and offset/limit for v1 APIs

• Error Handling: Comprehensive error handling with detailed error messages

• Type Safety: Full TypeScript implementation with proper type definitions

Prerequisites

• Node.js (v16 or higher)

• npm or yarn

• Atlassian account with API token

• Docker (optional, for containerized deployment)

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

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

MCP configuration

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)

Architecture Notes

Confluence API Migration

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

Tool Filtering & Security

• 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

Development

Project Structure

Building

Testing

Makefile Commands

The project includes a Makefile to simplify common operations:

License

MIT

Contributing

1. Fork the repository

2. Create your feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add some amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request