@amgisllc/atlassian-mcp

A Model Context Protocol (MCP) server for interacting with Jira and Confluence APIs. This server provides tools to manage Jira issues and Confluence pages directly from Claude or other MCP-compatible clients.

Features

Jira Operations

• Search issues with JQL or natural language queries
• Create, read, update, and delete issues (including bulk operations)
• Add comments and manage transitions
• Sprint management (boards, sprints, move issues)
• Time tracking (worklog, estimates)
• Watchers management
• Issue linking and dependencies
• Advanced filtering and saved searches
• Assign issues to users
• Manage projects, components, and labels

Confluence Operations

• Search pages with CQL or filters
• Create, read, update, and delete pages
• Manage spaces
• Add comments to pages
• Copy and move pages
• Get page children and hierarchy
• Support for both storage and wiki markup formats

Installation

Option 1: Install from npm (Recommended)

npm install -g @amgisllc/atlassian-mcp

Or install locally in a project:

npm install @amgisllc/atlassian-mcp

Option 2: Install from source

1. Clone this repository
2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

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

# Jira Configuration
JIRA_DOMAIN=your-domain
[email protected]
JIRA_API_TOKEN=your-jira-api-token

# Confluence Configuration (optional, can use same as Jira)
CONFLUENCE_DOMAIN=your-domain
[email protected]
CONFLUENCE_API_TOKEN=your-confluence-api-token

Getting API Tokens

1. Go to Atlassian Account Settings
2. Click "Create API token"
3. Give it a descriptive name
4. Copy the token and use it in your .env file

Domain Configuration

The domain is the first part of your Atlassian URL:

• If your Jira URL is https://mycompany.atlassian.net, then JIRA_DOMAIN=mycompany
• Same applies for Confluence

Usage with Claude Desktop

Add the following to your Claude Desktop configuration file:

If installed globally via npm:

macOS/Linux

Edit ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@amgisllc/atlassian-mcp"],
      "env": {
        "JIRA_DOMAIN": "your-domain",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx.cmd",
      "args": ["-y", "@amgisllc/atlassian-mcp"],
      "env": {
        "JIRA_DOMAIN": "your-domain",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

If installed from source:

Use the full path to your built index.js file:

{
  "mcpServers": {
    "atlassian": {
      "command": "node",
      "args": ["/path/to/atlassian-mcp/dist/index.js"],
      "env": {
        "JIRA_DOMAIN": "your-domain",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

New in Version 1.1.0

Natural Language Queries

You can now use natural language to search for issues:

• "my open bugs in project TSA"
• "high priority tasks from last week"
• "unassigned issues created today"

Bulk Operations

Perform actions on multiple issues at once:

• Bulk update fields
• Bulk transitions
• Bulk delete

Sprint Management

Full agile board support:

• View boards and sprints
• Move issues between sprints
• Get sprint reports

Enhanced Features

• Time Tracking: Log work, update estimates
• Watchers: Add/remove watchers on issues
• Issue Links: Create dependencies between issues
• Smart Caching: Improved performance with intelligent caching
• Validation: Input validation and better error messages

Available Tools

Jira Tools

jira_search_issues

Search for Jira issues using JQL or filters.

• Parameters:
  • jql (optional): JQL query string
  • projectKey (optional): Filter by project
  • status (optional): Filter by status
  • assignee (optional): Filter by assignee
  • reporter (optional): Filter by reporter
  • maxResults (optional): Maximum results (default: 50)

jira_get_issue

Get details of a specific Jira issue.

• Parameters:
  • issueKey (required): Issue key (e.g., PROJ-123)

jira_create_issue

Create a new Jira issue.

• Parameters:
  • projectKey (required): Project key
  • summary (required): Issue summary
  • issueTypeName (required): Issue type (Bug, Task, Story, etc.)
  • description (optional): Issue description
  • priority (optional): Priority level
  • assigneeAccountId (optional): Assignee's account ID
  • labels (optional): Array of labels
  • components (optional): Array of components
  • customFields (optional): Custom field values

jira_update_issue

Update an existing Jira issue.

• Parameters:
  • issueKey (required): Issue key
  • summary (optional): New summary
  • description (optional): New description
  • priority (optional): New priority
  • assigneeAccountId (optional): New assignee
  • labels (optional): New labels
  • components (optional): New components
  • customFields (optional): Custom field updates

jira_delete_issue

Delete a Jira issue.

• Parameters:
  • issueKey (required): Issue key to delete

jira_add_comment

Add a comment to a Jira issue.

• Parameters:
  • issueKey (required): Issue key
  • comment (required): Comment text

jira_transition_issue

Transition an issue to a different status.

• Parameters:
  • issueKey (required): Issue key
  • transitionName or transitionId: Transition to apply
  • comment (optional): Transition comment
  • resolution (optional): Resolution for closed issues

jira_get_projects

Get list of all accessible Jira projects.

jira_get_issue_types

Get available issue types for a project.

• Parameters:
  • projectKey (required): Project key

jira_assign_issue

Assign an issue to a user.

• Parameters:
  • issueKey (required): Issue key
  • accountId (required): User's account ID

jira_get_comments

Get all comments for an issue.

• Parameters:
  • issueKey (required): Issue key

jira_search_users

Search for Jira users.

• Parameters:
  • query (optional): Search query

Confluence Tools

confluence_search_content

Search for Confluence pages.

• Parameters:
  • cql (optional): CQL query string
  • spaceKey (optional): Filter by space
  • title (optional): Filter by title
  • text (optional): Search in content
  • limit (optional): Maximum results (default: 25)

confluence_get_page

Get details of a specific page.

• Parameters:
  • pageId (required): Page ID

confluence_create_page

Create a new Confluence page.

• Parameters:
  • spaceKey (required): Space key
  • title (required): Page title
  • content (required): Page content
  • parentId (optional): Parent page ID
  • format (optional): Content format ('storage' or 'wiki')

confluence_update_page

Update an existing page.

• Parameters:
  • pageId (required): Page ID
  • title (optional): New title
  • content (optional): New content
  • versionMessage (optional): Version message
  • format (optional): Content format

confluence_delete_page

Delete a Confluence page.

• Parameters:
  • pageId (required): Page ID

confluence_get_spaces

Get list of all accessible spaces.

• Parameters:
  • limit (optional): Maximum results

confluence_get_space

Get details of a specific space.

• Parameters:
  • spaceKey (required): Space key

confluence_create_space

Create a new Confluence space.

• Parameters:
  • key (required): Space key
  • name (required): Space name
  • description (optional): Space description

confluence_get_page_children

Get child pages of a page.

• Parameters:
  • pageId (required): Parent page ID
  • limit (optional): Maximum results

confluence_add_page_comment

Add a comment to a page.

• Parameters:
  • pageId (required): Page ID
  • comment (required): Comment text

confluence_copy_page

Copy a page to a new location.

• Parameters:
  • pageId (required): Page to copy
  • newTitle (required): Title for the copy
  • targetSpaceKey (optional): Target space
  • targetParentId (optional): Target parent page

confluence_move_page

Move a page to a different location.

• Parameters:
  • pageId (required): Page to move
  • targetSpaceKey (optional): Target space
  • targetParentId (optional): Target parent page

Development

Run in development mode:

npm run dev

Build the project:

npm run build

Clean build artifacts:

npm run clean

Example Usage in Claude

Once configured, you can use commands like:

"Search for all open bugs in project ABC"
"Create a new task in project XYZ with title 'Update documentation'"
"Add a comment to issue ABC-123 saying 'This has been resolved'"
"Create a new Confluence page in space DOCS with title 'API Guide'"
"Search for Confluence pages containing 'deployment'"

Troubleshooting

Authentication Issues

• Ensure your API token is valid and not expired
• Verify the domain name is correct (without .atlassian.net)
• Check that your account has necessary permissions

Connection Issues

• Verify your internet connection
• Check if Atlassian services are operational
• Ensure firewall/proxy settings allow HTTPS connections

Permission Issues

• Verify your account has access to the projects/spaces
• Check project/space permissions in Atlassian admin settings
• Some operations may require admin privileges

Security Notes

• Never commit your .env file to version control
• Keep your API tokens secure and rotate them regularly
• Use environment variables or secure credential storage in production
• Consider using separate API tokens for different environments

License

MIT

Support

For issues or questions:

1. Check the Atlassian API documentation
2. Review the error messages returned by the tools
3. Ensure your API tokens have the necessary scopes
4. Check Atlassian service status