MCP_Custom_Atlassian_MCP_Server

HidekiAI-WORK/MCP_Custom_Atlassian_MCP_Server

3.1

If you are the rightful owner of MCP_Custom_Atlassian_MCP_Server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

This document provides a comprehensive guide for setting up a standalone Python MCP server to integrate Atlassian services with Claude Desktop, bypassing SSL certificate issues.

MCP for Claude Desktop to Query with Atlassian Confluence

Inspired by https://github.com/sooperset/mcp-atlassian which is a Docker-based solution. This version is a standalone Python script that uses curl for API calls, making it easier to set up without Docker dependencies. If you can manage to run Docker, you can use the original solution instead which is more robust and feature-complete. This version is designed to work around SSL certificate issues that can occur in corporate environments, where Python's requests library may fail due to SSL handshake problems.

Overview

This solution creates a standalone Python MCP server that uses curl to make API calls to Atlassian, avoiding SSL handshake issues that can occur with Python's requests library in corporate network environments.

Custom Atlassian MCP Server for Claude Desktop

This guide provides a complete setup for integrating Atlassian (Jira and Confluence) with Claude Desktop using a custom MCP (Model Context Protocol) server that bypasses SSL certificate issues commonly encountered in corporate environments.

Features

  • Jira Integration: Search issues with JQL, get detailed issue information
  • Confluence Integration: Search pages, get recent documents
  • SSL Issue Bypass: Uses curl instead of Python requests to avoid certificate problems
  • No Docker Required: Runs as a standalone Python script
  • Full MCP Protocol: Complete integration with Claude Desktop

Files Created/Modified

New Files to Create

  1. custom_mcp_atlassian.py - Main MCP server script
    • Location: ~/Library/Application Support/Claude/MCP/MCP_Custom_Atlassian_MCP_Server/custom_mcp_atlassian.py
    • Purpose: Standalone MCP server using curl for API calls

Files to Modify

  1. claude_desktop_config.json - Claude Desktop configuration
    • Location: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Purpose: Configure Claude Desktop to use the custom MCP server

Prerequisites

  • macOS with Claude Desktop installed
  • Python 3 (usually pre-installed on macOS)
  • curl (pre-installed on macOS)
  • Atlassian API Token (instructions below)

Tools, Utilities, and Libraries

  • Python 3: Usually pre-installed on macOS
  • curl: Pre-installed on macOS
  • Claude Desktop: Installed and configured on your macOS system

Claude Desktop Configuration

  • File: claude_desktop_config.json
  • Location: ~/Library/Application Support/Claude/claude_desktop_config.json (for macOS)
  • Action: Replace entire file (after backing up)
  • Purpose: Configure Claude Desktop to use the custom MCP server
  • Critical Settings:
    • Server command: python3
    • Script path: Full path to custom_mcp_atlassian.py
    • Environment variables: Atlassian URLs, username, API token

Setup Instructions

Step 1: Generate Atlassian API Token

  1. Go to Atlassian API Tokens
  2. Click "Create API token"
  3. Give it a descriptive name (e.g., "Claude MCP Access")
  4. Copy the generated token (save it securely, i.e. in the 'Notes' section of your 1Password for your Atlassian account)

Step 2: Create the MCP Server Script

mkdir -p ~/Library/Application\ Support/Claude/MCP
cd ~/Library/Application\ Support/Claude/MCP
git clone https://github.com/HidekiAI-WORK/MCP_Custom_Atlassian_MCP_Server.git`
cd MCP_Custom_Atlassian_MCP_Server

Step 3: Make the Script Executable

chmod +x ~/Library/Application\ Support/Claude/MCP/MCP_Custom_Atlassian_MCP_Server/custom_mcp_atlassian.py

Step 4: Configure Claude Desktop

āš ļø Important: Back up your existing configuration first!

# Backup existing config
cp ~/Library/Application\ Support/Claude/claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json.backup

Create or update the Claude Desktop configuration:

cat > ~/Library/Application\ Support/Claude/claude_desktop_config.json << 'EOF'
{
    "globalShortcut": "Cmd+.",
    "mcpServers": {
        "custom-atlassian": {
            "command": "python3",
            "args": ["/Users/YOUR_USERNAME/Library/Application Support/Claude/MCP/MCP_Custom_Atlassian_MCP_Server/custom_mcp_atlassian.py"],
            "env": {
                "JIRA_URL": "https://YOUR_COMPANY.atlassian.net",
                "CONFLUENCE_URL": "https://YOUR_COMPANY.atlassian.net/wiki",
                "JIRA_USERNAME": "your.email@company.com",
                "JIRA_API_TOKEN": "YOUR_API_TOKEN_HERE"
            }
        }
    }
}
EOF

Alternatively, you can use a text editor to create or modify the claude_desktop_config.SAMPLE.json file with the above content.

Replace the following placeholders:

  • YOUR_USERNAME - Your macOS username (run whoami to find it)
  • YOUR_COMPANY - Your Atlassian subdomain
  • your.email@company.com - Your Atlassian account email
  • YOUR_API_TOKEN_HERE - The API token you generated in Step 1

Step 5: Restart Claude Desktop

  1. Completely quit Claude Desktop (not just close the window)
  2. Wait a few seconds
  3. Relaunch Claude Desktop from Applications
  4. Go to "Settings" -> "Integrations"
    • You should see "custom-atlassian LOCAL"
    • If it doesn't appear, go to "General Settings" (Command + ,) -> Developer -> "custom-atlassian" and look for any errors

Testing the Setup

Test Direct API Access First

Before testing with Claude Desktop, verify your API credentials work:

# Test Jira API
curl -u "your.email@company.com:YOUR_API_TOKEN" \
     "https://YOUR_COMPANY.atlassian.net/rest/api/2/search?jql=updated%20%3E%3D%20-7d&maxResults=1"

# Test Confluence API
curl -u "your.email@company.com:YOUR_API_TOKEN" \
     "https://YOUR_COMPANY.atlassian.net/wiki/rest/api/content/search?cql=type=page&limit=1"

Test with Claude Desktop

Once Claude Desktop is restarted, you can ask Claude:

  • "What are my recent Jira issues?"
  • "Search for Jira issues updated in the last 7 days"
  • "What was my last Confluence document?"
  • "Get details for issue WAP-123"
  • "Search Confluence for pages about 'project name'"

Available Commands

Jira Commands

  1. Search Issues:

    • Query: "Search for Jira issues with JQL: project = ABC"
    • Uses: jira_search tool

  2. Get Issue Details:

    • Query: "Get details for Jira issue ABC-123"
    • Uses: jira_get_issue tool

Confluence Commands

  1. Recent Pages:

    • Query: "What are my recent Confluence documents?"
    • Uses: confluence_search tool with no query

  2. Search Pages:

    • Query: "Search Confluence for pages about 'project name'"
    • Uses: confluence_search tool with query

  3. Sample Query:

    • Query: "Proof read the latest Confluence document I've written and find related documents similar to mine so I can add them to my 'See also' block"
    • Uses: confluence_search

Common JQL Examples

  • updated >= -7d - Issues updated in last 7 days
  • project = ABC AND status = "In Progress" - In-progress issues in project ABC
  • assignee = currentUser() - Issues assigned to you
  • labels = "urgent" - Issues with "urgent" label
  • created >= startOfWeek() - Issues created this week

Troubleshooting

MCP Server Not Connecting

  1. Check Claude Desktop logs (if available)

  2. Verify file paths in the configuration match your system

  3. Test the Python script directly:

    export JIRA_URL="https://YOUR_COMPANY.atlassian.net"
export CONFLUENCE_URL="https://YOUR_COMPANY.atlassian.net/wiki"
export JIRA_USERNAME="your.email@company.com"
export JIRA_API_TOKEN="YOUR_API_TOKEN"

# Test basic functionality
echo '{"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}},"jsonrpc":"2.0","id":1}' | python3 ~/Library/Application\ Support/Claude/MCP/MCP_Custom_Atlassian_MCP_Server/custom_mcp_atlassian.py

API Access Issues

  1. Verify API token is correct and has proper permissions
  2. Check Atlassian URLs are correct
  3. Test curl commands manually first
  4. Ensure network access to Atlassian instance

SSL Certificate Issues

This solution specifically addresses SSL issues by using curl instead of Python requests. If you still encounter SSL problems:

  1. Check corporate firewall/proxy settings
  2. Verify curl works from command line
  3. Contact IT if corporate network blocks API access

File Structure Summary

/Users/hideki.ikeda/Library/Application\ Support/Claude
ā”œā”€ā”€ MCP
|   ā”œā”€ā”€ MCP_Custom_Atlassian_MCP_Server
|   |   ā”œā”€ā”€ LICENSE
|   |   ā”œā”€ā”€ README.md
|   |   ā”œā”€ā”€ claude_desktop_config.SAMPLE.json
|   |   ā”œā”€ā”€ custom_mcp_atlassian.py    # Main MCP server script
|   |   ā””ā”€ā”€ docs
|   |       ā”œā”€ā”€ Sample-Query-confluence_search.png
|   |       ā”œā”€ā”€ Settings-Developer-MCP-Status.png
|   |       ā”œā”€ā”€ User-Settings-Integrations-MCP-Details.png
|   |       ā””ā”€ā”€ User-Settings-Integrations-MCP.png
|   ā””ā”€ā”€ some_other_MCP_projects
|       ā””ā”€ā”€ MCP script.ts
ā”œā”€ā”€ claude_desktop_config.json   # MCP server configuration
ā”œā”€ā”€ claude_desktop_config.json.backup   # Optional: Backup of original config
ā”œā”€ā”€ config.json
ā””ā”€ā”€ more_dirs_and_files

VSCode Extension

When you have Roo extensions installed on VSCode, it will automagically detect your Claude Desktop configurations, and will let you add MCP via "Command Pallette" -> "MCP: List Servers" -> "custom Atlassian Server" (if it doesn't appear, possibly Claude Desktop isn't running?)

You can also have it auto-start via "Command Pallette" -> "MCP Servers" -> "Edit Global MCP"

Note that I have the Python version disabled. Sample settings:

{
  "mcpServers": {
    "custom-atlassian-server-JS": {
      "command": "node",
      "args": [
        "/Users/__USERNAME__/Library/Application Support/Claude/MCP/MCP_Custom_Atlassian_MCP_Server/dist/atlassian_mcp_server.js"
      ],
      "env": {
        "JIRA_URL": "https://__YOUR_COMPANY__.atlassian.net",
        "CONFLUENCE_URL": "https://__YOUR_COMPANY__.atlassian.net/wiki",
        "JIRA_USERNAME": "__USERNAME__@__YOUR_COMPANY__.com",
        "JIRA_API_TOKEN": "_SOME_API_KEY_ACQUIRED_FROM_ATLASSIAN_"
      }
    },
    "custom-atlassian-server-Py": {
      "command": "python3",
      "args": [
        "/Users/__USERNAME__/Library/Application Support/Claude/MCP/MCP_Custom_Atlassian_MCP_Server/custom_mcp_atlassian.py"
      ],
      "env": {
        "JIRA_URL": "https://__YOUR_COMPANY__.atlassian.net",
        "CONFLUENCE_URL": "https://__YOUR_COMPANY__.atlassian.net/wiki",
        "JIRA_USERNAME": "__USERNAME__@__YOUR_COMPANY__.com",
        "JIRA_API_TOKEN": "_SOME_API_KEY_ACQUIRED_FROM_ATLASSIAN_"
      },
      "disabled": true,
      "alwaysAllow": []
    }
  }
}

And finally, VSCode under

Note that "Found 0 Confluence pages" for simple query of "NDT" should have found something... But it is connected, or else I would have got a "503" (Service Unavailable) error or a "400" (Bad Request) error, but for the sake of this documentation, that's not relevant for now...

Security Notes

  • API tokens have sensitive access - store them securely
  • Back up your Claude Desktop configuration before making changes
  • Review permissions granted to the API token
  • Consider using environment variables instead of hardcoding credentials

Sharing with Colleagues

When sharing this setup:

  1. Share this README.md with complete instructions
  2. Share the custom_mcp_atlassian.py script
  3. Each person needs their own API token
  4. Update URLs and usernames for each person's setup
  5. Test thoroughly in each environment

Credits

This solution was developed to overcome SSL certificate issues commonly encountered when integrating corporate Atlassian instances with Claude Desktop's MCP protocol. It uses curl for API calls instead of Python's requests library to bypass SSL handshake problems in corporate network environments.