convez.ai
MCP ServerIntegração & APIsIntermediário
Vijay-Duke

MCP Atlassian Server

Vijay-Duke/mcp-atlassian

Integre Jira e Confluence com Claude via MCP

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP para integração com Atlassian (Jira e Confluence), permitindo que assistentes de IA leiam, criem e gerenciem issues, páginas, comentários e attachments. Fork mantido que corrige quebras de API do Jira em janeiro de 2026 com suporte a endpoints JQL atualizados.

Instalação

$npx convez-ai Vijay-Duke/mcp-atlassian

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
7
Acompanhando
0
Saúde
85%
Último commit
há 3 dias
Versão
v2.1.0
Issues abertas
28
Contribuidores
6

Casos de uso

  • Consultar e criar issues no Jira automaticamente
  • Buscar e gerenciar páginas Confluence
  • Exportar documentação como HTML ou Markdown
  • Gerenciar comentários e anexos em projetos
  • Acompanhar sprints e boards do Jira

Veredito

Ferramenta sólida para automatizar workflows Atlassian via Claude. O fork mantém compatibilidade com APIs recentes (JQL), mas requer configuração de tokens e experiência com MCP para integração plena. Excelente para equipes que já usam Jira/Confluence e querem IA nativa nessas plataformas.

README

A tradução para o português deste README ainda está na fila.

MCP Atlassian Server

This is a maintained fork of Vijay-Duke/mcp-atlassian

Why this fork exists: In January 2026, Atlassian removed the /rest/api/3/search endpoint entirely, breaking all Jira search functionality in the original package. This fork migrates to the new /rest/api/3/search/jql endpoint and implements the new cursor-based pagination. A PR has been submitted to upstream, but as of now there are 14+ unmerged PRs in that repo.

Install this fork: npm install @efithor/mcp-atlassian --registry=https://npm.pkg.github.com

License: MIT

A Model Context Protocol (MCP) server for integrating with Atlassian products (Confluence and Jira). This server provides tools for AI assistants to interact with Atlassian Cloud APIs, enabling document management, search, and export capabilities.

Features

Confluence Integration

  • Read & Search: Access pages, spaces, and content
  • Content Management: Create, update pages and comments
  • Page Hierarchy: Navigate parent/child page relationships
  • Export: Export pages as HTML or Markdown with embedded images
  • Attachments: List, download, and upload attachments
  • Labels: Manage page labels
  • Users: Find and query users, track personal activity
  • Personal Dashboard: View recent pages and mentions

Jira Integration

  • Issues: Read and search issues, get personal tasks
  • Projects: List and explore projects
  • Boards & Sprints: List boards, view sprints, track active work
  • Comments: Add comments to issues
  • Issue Creation: Create new issues with custom fields
  • User Management: Get current user details
  • Personal Dashboard: View your open issues and sprint tasks

Installation

Option 1: GitHub Packages (Recommended)

First, configure npm to use GitHub Packages for the @efithor scope. Add to your ~/.npmrc:

@efithor:registry=https://npm.pkg.github.com

Then install:

# Install globally
npm install -g @efithor/mcp-atlassian

# Or install locally
npm install @efithor/mcp-atlassian

Option 2: Clone and Build

# Clone this fork
git clone https://github.com/Efithor/mcp-atlassian.git
cd mcp-atlassian

# Install dependencies
npm install

# Build TypeScript
npm run build

Option 3: Install Directly from GitHub

# Install directly from this fork
npm install -g github:Efithor/mcp-atlassian

# Or install in your project
npm install github:Efithor/mcp-atlassian

Configuration

Environment Variables

Create a .env file in the root directory:

ATLASSIAN_BASE_URL=https://yourdomain.atlassian.net
ATLASSIAN_EMAIL=your-email@example.com
ATLASSIAN_API_TOKEN=your-api-token

Getting API Token

  1. Log in to Atlassian Account Settings
  2. Click "Create API token"
  3. Give it a label and copy the token
  4. Use this token in your .env file

MCP Settings Configuration

Add to your Claude Desktop config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Option 1: After npm install -g

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "npx",
      "args": ["@efithor/mcp-atlassian"],
      "env": {
        "ATLASSIAN_BASE_URL": "https://yourdomain.atlassian.net",
        "ATLASSIAN_EMAIL": "your-email@example.com",
        "ATLASSIAN_API_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

Option 2: From Local Clone

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "node",
      "args": ["/path/to/your/mcp-atlassian/dist/index.js"],
      "env": {
        "ATLASSIAN_BASE_URL": "https://yourdomain.atlassian.net",
        "ATLASSIAN_EMAIL": "your-email@example.com",
        "ATLASSIAN_API_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

Example with typical paths:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "node",
      "args": ["~/projects/mcp-atlassian/dist/index.js"],
      "env": {
        "ATLASSIAN_BASE_URL": "https://yourdomain.atlassian.net",
        "ATLASSIAN_EMAIL": "your.email@company.com",
        "ATLASSIAN_API_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

Option 3: Direct from GitHub using uvx (Coming Soon)

You can run the server directly from GitHub without cloning:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Efithor/mcp-atlassian.git", "mcp-atlassian"],
      "env": {
        "ATLASSIAN_BASE_URL": "https://yourdomain.atlassian.net",
        "ATLASSIAN_EMAIL": "your-email@example.com",
        "ATLASSIAN_API_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

Note: The uvx method requires the package to be properly configured for Python packaging. This is planned for a future release.

Available Tools

Confluence Tools

ToolDescription
get_confluence_current_userGet details of the authenticated user
get_confluence_userGet details for a specific user
search_confluence_pages_by_userSearch pages by user activity
list_user_confluence_pagesList pages authored by a user
list_user_confluence_attachmentsList attachments uploaded by a user
read_confluence_pageRead a Confluence page by ID or title
search_confluence_pagesSearch pages using CQL (Confluence Query Language)
list_confluence_spacesList all accessible spaces
get_confluence_spaceGet details of a specific space
create_confluence_pageCreate a new page
update_confluence_pageUpdate existing page content
list_confluence_page_childrenList child pages of a page
list_confluence_page_ancestorsGet parent hierarchy of a page
export_confluence_pageExport page as HTML or Markdown with embedded images
list_confluence_attachmentsList page attachments
download_confluence_attachmentDownload specific attachment
upload_confluence_attachmentUpload file to a page
download_confluence_page_completeDownload page with all content
add_confluence_commentAdd comment to a page
list_confluence_page_labelsGet page labels
add_confluence_page_labelAdd labels to a page
find_confluence_usersSearch for users
get_my_recent_confluence_pagesList your recent pages
get_confluence_pages_mentioning_meFind pages that mention you

Jira Tools

ToolDescription
get_jira_current_userGet details of the authenticated user
get_jira_userGet details for a specific user
search_jira_issues_by_userSearch issues by user involvement
list_user_jira_issuesList issues by user role with date filtering
get_user_jira_activityTrack user activity including comments and transitions
get_user_jira_worklogGet time tracking entries with formatted totals
read_jira_issueRead issue details by key
search_jira_issuesSearch issues using JQL
list_jira_projectsList all accessible projects
create_jira_issueCreate new issue
add_jira_commentAdd comment to issue
list_jira_boardsList accessible Scrum/Kanban boards
list_jira_sprintsList sprints for a board
get_jira_sprintGet detailed sprint information
get_my_tasks_in_current_sprintGet your tasks in active sprints
get_my_open_issuesGet all your open issues

Usage Examples

Export Confluence Page

// Export as HTML (raw content with embedded images)
{
  "tool": "export_confluence_page",
  "arguments": {
    "pageId": "123456789",
    "format": "html"
  }
}

// Export as Markdown with metadata
{
  "tool": "export_confluence_page",
  "arguments": {
    "pageId": "123456789",
    "format": "markdown"
  }
}

Search Confluence

{
  "tool": "search_confluence_pages",
  "arguments": {
    "cql": "space=DEV AND text~'architecture'",
    "limit": 10
  }
}

Create Jira Issue

{
  "tool": "create_jira_issue",
  "arguments": {
    "projectKey": "PROJ",
    "issueType": "Task",
    "summary": "Implement new feature",
    "description": "Detailed description here",
    "priority": "Medium"
  }
}

Get Your Sprint Tasks

// Get your tasks in the current sprint
{
  "tool": "get_my_tasks_in_current_sprint",
  "arguments": {
    "projectKey": "PROJ"
  }
}

// Get all your open issues
{
  "tool": "get_my_open_issues",
  "arguments": {
    "projectKeys": ["PROJ1", "PROJ2"],
    "maxResults": 50
  }
}

Work with Boards and Sprints

// List boards for a project
{
  "tool": "list_jira_boards",
  "arguments": {
    "projectKeyOrId": "PROJ",
    "type": "scrum"
  }
}

// Get active sprints for a board
{
  "tool": "list_jira_sprints",
  "arguments": {
    "boardId": 123,
    "state": "active"
  }
}

User-Specific Jira Operations

// Get user details
{
  "tool": "get_jira_user",
  "arguments": {
    "username": "john.doe"
  }
}

// Search issues by user involvement
{
  "tool": "search_jira_issues_by_user",
  "arguments": {
    "username": "john.doe",
    "searchType": "assignee",
    "status": "In Progress",
    "maxResults": 20
  }
}

// Get user's work logs
{
  "tool": "get_user_jira_worklog",
  "arguments": {
    "username": "john.doe",
    "startDate": "2024-01-01",
    "endDate": "2024-01-31",
    "projectKeys": ["PROJ1", "PROJ2"]
  }
}

// Track user activity
{
  "tool": "get_user_jira_activity",
  "arguments": {
    "username": "john.doe",
    "activityType": "all",
    "days": 7
  }
}

Content Format Support

Markdown ↔ Confluence Storage Format

The server automatically converts between Markdown and Confluence's storage format:

  • Write content in Markdown when creating/updating pages
  • Read pages in either storage format or converted to Markdown
  • Preserves formatting, links, and structure

Export Formats

  • HTML: Raw Confluence HTML with all images embedded as base64 data URIs
  • Markdown: Clean Markdown with YAML frontmatter, includes metadata and embedded images

Development

# Run in development mode with console logging
npm run dev

# Build for production
npm run build

# Run built server in MCP mode (no console output)
npm start

# Run built server in development mode (with console output)
npm run start:dev

# Run tests
npm test

Logging Behavior

The server defaults to MCP mode where console output is disabled to prevent interference with the JSON-RPC protocol. Console logging is only enabled when MCP_SERVER_MODE=false is set, which is done automatically by the dev and start:dev scripts.

Project Structure

mcp-atlassian/
├── src/
│   ├── index.ts                 # Main server entry point
│   ├── types/                   # TypeScript type definitions
│   ├── confluence/
│   │   ├── handlers.ts          # Confluence API handlers
│   │   └── tools.ts             # Tool definitions
│   ├── jira/
│   │   ├── handlers.ts          # Jira API handlers
│   │   └── tools.ts             # Tool definitions
│   └── utils/
│       ├── http-client.ts       # Axios HTTP client setup
│       ├── content-converter.ts # Markdown ↔ Storage conversion
│       └── export-converter.ts  # HTML/Markdown export utilities
├── dist/                        # Compiled JavaScript
├── .env                         # Environment variables (not in git)
├── package.json
└── tsconfig.json

Security Notes

  • API tokens are stored in environment variables, never in code
  • Uses Basic Authentication with API tokens (not passwords)
  • All requests are made over HTTPS
  • Supports Atlassian Cloud only (not Server/Data Center)

Limitations

  • No delete operations implemented (by design for safety)
  • Export to PDF requires browser conversion (HTML → Print → PDF)
  • Some Confluence macros may not convert perfectly to Markdown
  • Rate limits apply based on Atlassian Cloud API limits

CI/CD Pipeline

This project uses GitHub Actions for continuous integration and deployment.

Workflows

🔄 Continuous Integration (ci.yml)

  • Triggers: Push to main/develop, Pull requests
  • Jobs:
    • Test: Runs tests on Node.js 18.x, 20.x, and 22.x
    • Build: Compiles TypeScript and validates the build
    • Lint: Type checking and security audit
    • Validate Package: Ensures package size and structure

📦 Publish to npm (publish.yml)

  • Triggers: GitHub releases, Manual dispatch
  • Features:
    • Automatic version bumping
    • npm publishing with provenance
    • GitHub release creation
    • Changelog updates

🔒 Security Scanning (security.yml)

  • Triggers: Push to main, PRs, Weekly schedule
  • Scans:
    • npm audit for vulnerabilities
    • CodeQL analysis
    • OWASP dependency check
    • Snyk security scanning (optional)

🏷️ Release Management (release.yml)

  • Triggers: Version tags, Manual dispatch
  • Features:
    • Automatic changelog generation
    • GitHub release creation
    • Build artifacts attachment
    • Release notes formatting

✅ PR Validation (pr-validation.yml)

  • Triggers: Pull request events
  • Checks:
    • Semantic PR title validation
    • PR size labeling
    • Auto-labeling based on files changed

🤖 Automated Dependency Updates

Dependabot is configured to:

  • Check for npm dependency updates weekly
  • Check for GitHub Actions updates weekly
  • Group non-major updates together
  • Create PRs with proper labels

Setting Up CI/CD

Required GitHub Secrets

  1. NPM_TOKEN: npm authentication token for publishing

  2. SNYK_TOKEN (Optional): For Snyk security scanning

Branch Protection

Recommended branch protection rules for main:

  • Require PR reviews before merging
  • Require status checks to pass (CI tests)
  • Require branches to be up to date
  • Include administrators in restrictions

Local Development

Before pushing changes:

# Run tests locally
npm test

# Build the project
npm run build

# Check for security vulnerabilities
npm audit

# Type check
npx tsc --noEmit

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Support

For issues and questions:

Acknowledgments

Built with:

Contributors

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!

Ver o original no GitHub

Bom para

Relacionados