Skip to content
BSWEN
Blog

How to Use Atlassian MCP with Claude Code: A Beginner's Guide

Cowrie
Cowrie
Dev @ Bswen

Purpose

This post demonstrates how to use the Atlassian MCP skill in Claude Code to interact with Atlassian products like Jira and Confluence.

Environment

  • Claude Code with MCP support
  • Atlassian MCP skill installed
  • Atlassian Cloud account (Jira/Confluence)
  • Node.js 18+ (if running MCP server locally)

What is Atlassian MCP?

The Atlassian MCP (Model Context Protocol) skill allows Claude Code to interact with Atlassian Cloud APIs. Instead of switching between your development environment and Jira/Confluence, you can ask Claude to create issues, update tickets, or query documentation directly from your chat.

When I first tried this skill, I wanted to see what it could do:

Terminal window
# Ask Claude to use Atlassian MCP
"Use atlassian-mcp to list my Jira issues"

I got this response:

Claude invokes the Atlassian MCP skill and returns:
- Issue: DEV-1234 - Fix authentication bug (Status: In Progress)
- Issue: DEV-1235 - Update API documentation (Status: Todo)
- Issue: DEV-1236 - Refactor user service (Status: In Review)

You can see that I succeeded to interact with Jira without leaving Claude.

Installation

Step 1: Install MCP Server

First, install the Atlassian MCP server:

Terminal window
# Install globally
npm install -g @modelcontextprotocol/server-atlassian


# Or install locally in your project
npm install --save-dev @modelcontextprotocol/server-atlassian

Step 2: Configure Claude Code

Add the MCP server to your Claude Code configuration file:

~/.claude/mcp_config.json
{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-atlassian"],
      "env": {
        "ATLASSIAN_URL": "https://your-domain.atlassian.net",
        "ATLASSIAN_EMAIL": "[email protected]",
        "ATLASSIAN_API_TOKEN": "your-api-token"
      }
    }
  }
}

Step 3: Generate API Token

You need an Atlassian API token:

  1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
  2. Click “Create API token”
  3. Label it “Claude Code MCP”
  4. Copy the token and paste it in your config

I forgot this step first and got authentication errors. Once I added the token, everything worked.

Core Usage Patterns

Triggering the Skill

You can invoke Atlassian MCP with natural language:

Terminal window
# Create a Jira issue
"Create a Jira bug: Login fails after timeout"


# Update an issue
"Update DEV-1234 status to Done"


# Query issues
"Show all high-priority issues in DEV project"


# Search Confluence
"Search Confluence for 'deployment guide'"

Common Use Cases

1. Create Issues from Code Context

When I find a bug while coding:

Terminal window
# Claude detects the issue
"Create Jira issue for this bug: Null reference in UserService.login()"

Claude creates the issue with:

  • Title: “Null reference in UserService.login()”
  • Description: Includes stack trace and code context
  • Priority: Set based on severity
  • Assignee: Unassigned or you

2. Update Issues from Chat

Terminal window
"Add comment to DEV-1234: Fixed the null check. Ready for review."

3. Query Documentation

Terminal window
"Search Confluence for 'API rate limiting' and show me the page"

Practical Examples

Example 1: Creating a Bug Report

I was working on a feature and found an authentication bug. Instead of switching to Jira:

Terminal window
# Context: I just ran tests and got an error
"Create a Jira bug report for: Authentication token expires after 5 minutes instead of 1 hour"

Claude created:

{
  "project": {
    "key": "AUTH"
  },
  "summary": "Authentication token expires after 5 minutes instead of 1 hour",
  "description": "Token expiry is set to 300 seconds instead of 3600 seconds in auth_service.ts line 45",
  "issuetype": {
    "name": "Bug"
  },
  "priority": {
    "name": "High"
  }
}

I can explain the key parts:

  • project.key: Target Jira project
  • summary: Issue title from my prompt
  • description: Claude extracted context from my conversation
  • priority: Claude inferred “High” from “authentication” and “security” context

Example 2: Batch Updates

I had multiple related issues to update:

Terminal window
"Set status to 'In Progress' for DEV-1001, DEV-1002, DEV-1003"

Claude made three API calls sequentially. You can see that I succeeded to update all issues in one command.

I needed to find deployment procedures:

Terminal window
"Search Confluence for 'production deployment checklist'"

Claude returned:

Found 3 pages:
1. Production Deployment Checklist (Last updated: 2025-01-15)
2. Emergency Rollback Procedures (Last updated: 2024-12-20)
3. CI/CD Pipeline Documentation (Last updated: 2025-01-10)


Which page would you like me to read?

I replied:

Terminal window
"Read the first page and summarize the deployment steps"

Best Practices

DO ✓

1. Provide Clear Context

Terminal window
# GOOD: Specific issue
"Create Jira bug in PROJ project: Database timeout when fetching user profile"


# BAD: Vague request
"Create an issue"

2. Use Issue Keys

Terminal window
# GOOD: Reference specific issues
"Add comment to DEV-1234: Deployed to staging"


# BAD: Ambiguous reference
"Comment on that issue we discussed"

3. Specify Projects

Terminal window
# GOOD: Explicit project
"Show all issues in DEV project assigned to me"


# BAD: Assumes default
"Show my issues"  # Which project?

DON’T ✗

1. Don’t Skip Authentication

I tried using the skill without setting up the API token:

Terminal window
"Create Jira issue"
# Error: Authentication failed

The reason is that Atlassian requires API tokens for security. I generated a token and added it to the config.

2. Don’t Assume Permissions

Terminal window
# This fails if you lack permissions
"Delete issue DEV-9999"
# Error: You don't have permission to delete issues

3. Don’t Create Issues Without Context

Terminal window
# Claude can't guess details
"Create issue"
# Response: What type of issue? Which project? What's the title?

Why Use Atlassian MCP?

Before MCP, I would:

  1. Alt-tab to browser
  2. Navigate to Jira
  3. Click “Create”
  4. Fill out the form
  5. Copy-paste code context
  6. Submit

Now I just:

  1. Type natural language command
  2. Claude creates the issue with context

The key point is context preservation. Claude knows what I’m working on, so it automatically includes relevant details in the issue description.

Atlassian MCP works well with other skills:

  • git: “Create Jira issue for this commit failure”
  • github: “Link Jira issue DEV-1234 to this PR”
  • confluence-mcp: “Update Confluence page with these release notes”

Summary

In this post, I showed how to use the Atlassian MCP skill in Claude Code. The key point is that MCP lets you interact with Atlassian products (Jira, Confluence) through natural language, without leaving your development environment.

I covered:

  • Installation and configuration
  • Common usage patterns
  • Creating issues, updating status, searching documentation
  • Best practices for clear commands
  • Common mistakes to avoid

The Atlassian MCP skill is part of the broader MCP ecosystem, which standardizes how AI assistants interact with external tools. Instead of building custom integrations for each service, MCP provides a unified protocol.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: