# Atlassian MCP Server

A custom Model Context Protocol (MCP) server that provides integration with your enterprise Jira and Confluence instances.

## Features

### Jira Tools
- **jira_search_issues** - Search issues using JQL
- **jira_get_issue** - Get detailed information about a specific issue
- **jira_create_issue** - Create new issues
- **jira_update_issue** - Update existing issues (summary, description, status)
- **jira_add_comment** - Add comments to issues

### Confluence Tools
- **confluence_search** - Search pages using CQL
- **confluence_get_page** - Get page content by ID or title
- **confluence_create_page** - Create new pages
- **confluence_update_page** - Update existing pages

## Prerequisites

- Node.js v18 or higher
- An Atlassian Cloud account with access to Jira and/or Confluence
- API token for authentication

## Setup Instructions

### Step 1: Install Dependencies

Navigate to the server directory and install dependencies:

```bash
cd atlassian-mcp-server
npm install
```

### Step 2: Create API Token

1. Go to [https://id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Click **Create API token**
3. Give it a label (e.g., "MCP Server")
4. Copy the token (you won't be able to see it again!)

### Step 3: Configure Environment Variables

1. Copy the example environment file:
   ```bash
   cp .env.example .env
   ```

2. Edit the `.env` file with your information:
   ```env
   ATLASSIAN_DOMAIN=yourcompany.atlassian.net
   ATLASSIAN_EMAIL=your.email@company.com
   ATLASSIAN_API_TOKEN=your_api_token_here
   DEFAULT_JIRA_PROJECT=PROJ
   DEFAULT_CONFLUENCE_SPACE=DEV
   ```

   **Important**:
   - For `ATLASSIAN_DOMAIN`, only include the subdomain (e.g., `mycompany.atlassian.net`)
   - Do NOT include `https://` in the domain
   - Use your actual Atlassian account email
   - Paste the API token you created in Step 2

### Step 4: Build the Server

```bash
npm run build
```

### Step 5: Test the Server (Optional)

You can test if the server starts correctly:

```bash
npm start
```

If you see "Atlassian MCP Server running on stdio", it's working! Press Ctrl+C to stop.

### Step 6: Add to Claude Code Configuration

1. Find your Claude Code configuration file:
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

2. Add the server configuration. If the file doesn't exist or is empty, create it with:

   ```json
   {
     "mcpServers": {
       "atlassian": {
         "command": "node",
         "args": [
           "/Users/206632367@BWT3.COM/Documents/workspace/fd-github/atlassian-mcp-server/dist/index.js"
         ]
       }
     }
   }
   ```

   **Note**: Replace the path with the absolute path to your `dist/index.js` file.

   If you already have other MCP servers configured, just add the "atlassian" entry to the existing `mcpServers` object:

   ```json
   {
     "mcpServers": {
       "existing-server": {
         ...
       },
       "atlassian": {
         "command": "node",
         "args": [
           "/Users/206632367@BWT3.COM/Documents/workspace/fd-github/atlassian-mcp-server/dist/index.js"
         ]
       }
     }
   }
   ```

3. Save the file and **restart Claude Code** completely (quit and reopen).

## Usage Examples

Once connected, you can ask Claude to interact with your Jira and Confluence:

### Jira Examples

```
"Search for all open bugs in project ABC"
"Show me details of issue ABC-123"
"Create a task in project ABC with summary 'Update documentation'"
"Add a comment to issue ABC-123 saying 'Working on this now'"
"Update ABC-123 status to 'In Progress'"
```

### Confluence Examples

```
"Search for pages about 'API documentation' in the DEV space"
"Show me the content of the page titled 'Getting Started' in space DOCS"
"Create a new page in space DEV titled 'Meeting Notes' with content..."
"Update page 123456 with new content..."
```

## Troubleshooting

### Authentication Errors

If you get 401 Unauthorized errors:
- Verify your email is correct in `.env`
- Ensure your API token is valid and hasn't expired
- Check that you have access to the Jira/Confluence instance

### Connection Errors

If Claude can't connect to the server:
- Make sure you've run `npm run build`
- Verify the path in `claude_desktop_config.json` is absolute and correct
- Check that Node.js is in your PATH
- Restart Claude Code completely

### Tool Not Found

If Claude says it doesn't have access to Jira/Confluence tools:
- Ensure the server is listed in your MCP configuration
- Restart Claude Code
- Check the server logs for any startup errors

### Finding Your Claude Config File

**macOS**:
```bash
open ~/Library/Application\ Support/Claude/
```

**Windows**:
```
%APPDATA%\Claude\
```

## Development

To make changes to the server:

1. Edit files in `src/`
2. Rebuild: `npm run build`
3. Restart Claude Code to pick up changes

For development with auto-rebuild:
```bash
npm run watch
```

## Security Notes

- Your API token is stored locally in the `.env` file
- Never commit `.env` to version control
- The server only runs locally and communicates directly with your Atlassian instance
- All authentication uses HTTPS

## License

MIT