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

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

Clone the repository:

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

Install dependencies:

npm install
# or using make
make install

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

ATLASSIAN_HOST=https://your-domain.atlassian.net
[email protected]
ATLASSIAN_API_TOKEN=your-api-token

Docker Installation

Clone the repository:

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

Create a .env file as described above.

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)

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

src/
├── config/         # Configuration files
│   └── env.ts      # Environment configuration with validation
├── services/       # Service classes for Atlassian APIs
│   ├── confluencev2.ts    # Confluence v2 REST API service (primary)
│   ├── confluence.ts      # Legacy Confluence service (deprecated)
│   └── jira.ts           # Jira REST API service
├── tools/          # MCP tool implementations
│   ├── search-confluence.ts                    # Content search (v1 API)
│   ├── search-confluence-pages-by-title.ts     # Title search (v2 API)
│   ├── get-confluence-space.ts                 # Single space info
│   ├── get-confluence-spaces.ts                # All spaces list
│   ├── get-confluence-content.ts               # Page content by ID
│   ├── get-confluence-pages.ts                 # Pages in space
│   ├── get-confluence-child-pages.ts           # Child pages
│   ├── get-confluence-pages-by-label.ts        # Pages by label
│   ├── get-confluence-page-labels.ts           # Page labels
│   ├── add-confluence-page-labels.ts           # Add labels
│   ├── get-confluence-page-comments.ts         # Page comments
│   ├── add-confluence-page-comment.ts          # Add comment
│   ├── get-confluence-page-inline-comments.ts  # Inline comments
│   ├── confluence-create-page.ts               # Create page
│   ├── confluence-update-page.ts               # Update page
│   ├── update-confluence-page-title.ts         # Update title only
│   ├── confluence-delete-page.ts               # Delete page
│   ├── create-confluence-footer-comment.ts     # Footer comments
│   ├── search-jira-issues.ts                   # Jira search
│   ├── get-jira-issue.ts                       # Single issue
│   ├── jira-create-issue.ts                    # Create issue
│   ├── jira-update-issue.ts                    # Update issue
│   ├── jira-add-comment.ts                     # Add comment
│   ├── jira-get-transitions.ts                 # Get transitions
│   ├── jira-transition-issue.ts                # Transition issue
│   ├── jira-get-all-projects.ts                # All projects
│   ├── utils.ts                                 # Utility functions & PII filtering
│   └── index.ts                                # Tool exports
├── utils/          # Utility modules
│   └── tool-filter.ts      # Tool filtering and access control
└── index.ts        # Main entry point and server setup

Building

# Using npm
npm run build

# Using make
make build

Testing

# Using npm
npm test

# Using make
make test

Makefile Commands

The project includes a Makefile to simplify common operations:

# Display available commands
make help

License

MIT

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request