Skip to content

llms-install.md

Latest commit

 

History

History
274 lines (199 loc) · 9.34 KB

llms-install.md

File metadata and controls

274 lines (199 loc) · 9.34 KB

MCP Atlassian Server (by phuc-nt) Installation Guide for AI

Important Note: MCP Atlassian Server (by phuc-nt) is primarily developed and optimized for use with the Cline AI assistant. While it follows the MCP standard and can work with other compatible MCP clients, the best performance and experience are achieved with Cline.

Version Note: This guide is for MCP Atlassian Server v2.0.1. For detailed documentation on architecture, development, and usage, refer to the new documentation series in the /docs/knowledge/ directory.

System Requirements

  • macOS 10.15+ or Windows 10+
  • Atlassian Cloud account and API token
  • Cline AI assistant (main supported client)

Installation Options

You have two ways to install MCP Atlassian Server:

  1. Install from npm (recommended, easier) - Install directly from npm registry
  2. Clone & Build from source - Clone the GitHub repository and build locally

Option 1: Install from npm

This is the recommended method as it's simpler and lets you easily update to new versions.

Install the package globally

npm install -g @phuc-nt/mcp-atlassian-server

Or install in your project:

npm install @phuc-nt/mcp-atlassian-server

Find the installation path

After installation, you'll need to know the path to the package for Cline configuration:

# For global installation, find the global node_modules directory
npm root -g
# Output will be something like: /usr/local/lib/node_modules

# For local installation, the path will be in your project directory
# e.g., /your/project/node_modules/@phuc-nt/mcp-atlassian-server

The full path to the executable will be: <npm_modules_path>/@phuc-nt/mcp-atlassian-server/dist/index.js

Skip to Configure Cline section after installing from npm.

Option 2: Clone and Build from Source

Prerequisite Tools Check & Installation

Check Installed Tools

Verify that Git, Node.js, and npm are installed:

git --version
node --version
npm --version

If the above commands show version numbers, you have the required tools. If not, follow the steps below:

Install Git

macOS

Method 1: Using Homebrew (recommended)

# Install Homebrew if not available
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Git
brew install git

Method 2: Install Xcode Command Line Tools

xcode-select --install

Windows

  1. Download the Git installer from git-scm.com
  2. Run the installer with default options
  3. After installation, open Command Prompt or PowerShell and check: git --version

Install Node.js and npm

macOS

Method 1: Using Homebrew (recommended)

brew install node

Method 2: Using nvm (Node Version Manager)

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Install Node.js LTS
nvm install --lts

Windows

  1. Download Node.js installer from nodejs.org (choose LTS version)
  2. Run the installer with default options
  3. After installation, open Command Prompt or PowerShell and check: 
    node --version
npm --version

Step 1: Clone the Repository

# macOS/Linux
git clone https://github.com/phuc-nt/mcp-atlassian-server.git
cd mcp-atlassian-server

# Windows
git clone https://github.com/phuc-nt/mcp-atlassian-server.git
cd mcp-atlassian-server

Step 2: Install Dependencies

npm install

Step 3: Build the Project

npm run build

Configure Cline

MCP Atlassian Server is specifically designed for seamless integration with Cline. Below is the guide to configure Cline to connect to the server:

Determine the Full Path

For npm installation

If you installed the package via npm, you need the path to the installed package:

# For global npm installation
echo "$(npm root -g)/@phuc-nt/mcp-atlassian-server/dist/index.js"

# For local npm installation (run from your project directory)
echo "$(pwd)/node_modules/@phuc-nt/mcp-atlassian-server/dist/index.js"

For source code installation

First, determine the full path to your project directory:

# macOS/Linux
pwd

# Windows (PowerShell)
(Get-Location).Path

# Windows (Command Prompt)
cd

Then, add the following configuration to your cline_mcp_settings.json file:

{
  "mcpServers": {
    "phuc-nt/mcp-atlassian-server": {
      "disabled": false,
      "timeout": 60,
      "command": "node",
      "args": [
        "/path/to/mcp-atlassian-server/dist/index.js"
      ],
      "env": {
        "ATLASSIAN_SITE_NAME": "your-site.atlassian.net",
        "ATLASSIAN_USER_EMAIL": "your-email@example.com",
        "ATLASSIAN_API_TOKEN": "your-api-token"
      },
      "transportType": "stdio"
    }
  }
}

Replace:

  • For npm installation: Use the path to the npm package:
    • Global install: /path/to/global/node_modules/@phuc-nt/mcp-atlassian-server/dist/index.js
    • Local install: /path/to/your/project/node_modules/@phuc-nt/mcp-atlassian-server/dist/index.js
  • For source installation: Use the path you just obtained with pwd command
  • your-site.atlassian.net with your Atlassian site name
  • your-email@example.com with your Atlassian email
  • your-api-token with your Atlassian API token

Note for global npm installs: You can find the global node_modules path by running: npm root -g

Note for Windows: The path on Windows may look like C:\\Users\\YourName\\AppData\\Roaming\\npm\\node_modules\\@phuc-nt\\mcp-atlassian-server\\dist\\index.js (use \\ instead of /).

Step 5: Get Atlassian API Token

  1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
  2. Click "Create API token", name it (e.g., "MCP Server")
  3. Copy the token immediately (it will not be shown again)

Note on API Token Permissions

  • The API token inherits all permissions of the account that created it – there is no separate permission mechanism for the token itself.
  • To use all features of MCP Server, the account creating the token must have appropriate permissions:
    • Jira: Needs Browse Projects, Edit Issues, Assign Issues, Transition Issues, Create Issues, etc.
    • Confluence: Needs View Spaces, Add Pages, Add Comments, Edit Pages, etc.
  • If the token is read-only, you can only use read resources (view issues, projects) but cannot create/update.
  • Recommendations:
    • For personal use: You can use your main account's token
    • For team/long-term use: Create a dedicated service account with appropriate permissions
    • Do not share your token; if you suspect it is compromised, revoke and create a new one
  • If you get a "permission denied" error, check the permissions of the account that created the token on the relevant projects/spaces

Summary: MCP Atlassian Server works best when using an API token from an account with all the permissions needed for the actions you want the AI to perform on Jira/Confluence.

Security Warning When Using LLMs

  • Security risk: If you or the AI in Cline ask an LLM to read/analyze the cline_mcp_settings.json file, your Atlassian token will be sent to a third-party server (OpenAI, Anthropic, etc.).
  • How it works:
    • Cline does NOT automatically send config files to the cloud
    • However, if you ask to "check the config file" or similar, the file content (including API token) will be sent to the LLM endpoint for processing
  • Safety recommendations:
    • Do not ask the LLM to read/check config files containing tokens
    • If you need support, remove sensitive information before sending to the LLM
    • Treat your API token like a password – never share it in LLM prompts

Important: If you do not ask the LLM to read the config file, your API token will only be used locally and will not be sent anywhere.

Documentation Resources

MCP Atlassian Server (by phuc-nt) now includes a comprehensive documentation series:

  1. MCP Overview & Architecture: Core concepts, architecture, and design principles
  2. MCP Tools & Resources Development: How to develop and extend MCP resources and tools
  3. MCP Prompts & Sampling: Guide for prompt engineering and sampling with MCP

These documents provide deeper insights into the server's functionality and are valuable for both users and developers.

Verify Installation

Test the MCP Server directly

You can test that the MCP Server runs correctly by executing it directly:

# For npm global install
node $(npm root -g)/@phuc-nt/mcp-atlassian-server/dist/index.js

# For npm local install
node ./node_modules/@phuc-nt/mcp-atlassian-server/dist/index.js

# For source code install
node ./dist/index.js

You should see output indicating that the server has started and registered resources and tools.

Test with Cline

After configuration, test the connection by asking Cline a question related to Jira or Confluence, for example:

  • "List all projects in Jira"
  • "Search for Confluence pages about [topic]"
  • "Create a new issue in project DEMO"

Cline is optimized to work with this MCP Atlassian Server (by phuc-nt) and will automatically use the most appropriate resources and tools for your queries.