# Atlassian MCP

A custom [Model Context Protocol](https://modelcontextprotocol.io) server that lets
AI agents interact with **Jira** and **Confluence** on Atlassian Cloud. It makes
plain REST calls in the background using the
[Jira REST API v3](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/)
and the
[Confluence REST API v2](https://developer.atlassian.com/cloud/confluence/rest/v2/intro/).

## Setup

1. Install dependencies and build:

   ```bash
   npm install
   npm run build
   ```

2. Expose the server as a global command so it can be launched from any
   workspace (uses the `bin` entry in `package.json`):

   ```bash
   npm link
   ```

   This puts an `atlassian-mcp` command on your `PATH`. Re-run `npm run build`
   after code changes; the linked command always points at the current `dist`.

3. Create an API token at
   <https://id.atlassian.com/manage-profile/security/api-tokens>.

4. Provide credentials via environment variables (see [.env.example](.env.example)):

   | Variable               | Description                                        |
   | ---------------------- | -------------------------------------------------- |
   | `ATLASSIAN_SITE_URL`   | Your site, e.g. `https://your-domain.atlassian.net`|
   | `ATLASSIAN_EMAIL`      | The email of your Atlassian account                |
   | `ATLASSIAN_API_TOKEN`  | The API token created above                        |

## Connecting a client

### VS Code (recommended)

This repo ships a standard [`.vscode/mcp.json`](.vscode/mcp.json). It launches the
server through a login + interactive zsh (`zsh -lic`) so it inherits the Atlassian
credentials exported in your `~/.zshrc` (or `~/.zshenv`) — no secrets in the config
— and calls the globally linked `atlassian-mcp` command so it works regardless of
which repo is open:

```json
{
  "servers": {
    "atlassian": {
      "type": "stdio",
      "command": "zsh",
      "args": ["-lic", "exec atlassian-mcp"]
    }
  }
}
```

> Avoid `${workspaceFolder}` here: it resolves to whatever repo is currently
> open, so it would break when the server is used from other workspaces. The
> `npm link` command name is resolved from your shell `PATH` instead.

To make the server available in **every** workspace, add the same `servers` block
to your user-level MCP config (Command Palette → *MCP: Open User Configuration*).

#### Alternative: run `node` with an absolute path

If you'd rather not `npm link`, point `node` directly at the built entry file
using an absolute path (not `${workspaceFolder}`, which changes per workspace).
VS Code's `${userHome}` variable keeps it portable across machines:

```json
{
  "servers": {
    "atlassian": {
      "type": "stdio",
      "command": "zsh",
      "args": ["-lic", "exec node \"${userHome}/Sites/atlassian-mcp/dist/index.js\""]
    }
  }
}
```

Adjust the path if you cloned the repo elsewhere. The `zsh -lic` wrapper still
supplies the credentials from your shell profile.

Export the variables in your shell profile instead of the config file:

```bash
export ATLASSIAN_SITE_URL="https://your-domain.atlassian.net"
export ATLASSIAN_EMAIL="you@example.com"
export ATLASSIAN_API_TOKEN="your-api-token"
```

Reload the VS Code window after changing your shell profile so the new values are
picked up.

### Other clients (Claude Desktop, Cline, Cursor)

Clients that don't run through your shell can either use the same `zsh -lic`
wrapper or set the variables explicitly:

```json
{
  "mcpServers": {
    "atlassian": {
      "command": "atlassian-mcp",
      "env": {
        "ATLASSIAN_SITE_URL": "https://your-domain.atlassian.net",
        "ATLASSIAN_EMAIL": "you@example.com",
        "ATLASSIAN_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

Without `npm link`, use `node` with an absolute path to the built entry file:

```json
{
  "mcpServers": {
    "atlassian": {
      "command": "node",
      "args": ["/absolute/path/to/atlassian-mcp/dist/index.js"],
      "env": {
        "ATLASSIAN_SITE_URL": "https://your-domain.atlassian.net",
        "ATLASSIAN_EMAIL": "you@example.com",
        "ATLASSIAN_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

For local development you can run the server directly with `npm run dev`.

## Tools

### Jira

| Tool                     | Description                                     |
| ------------------------ | ----------------------------------------------- |
| `jira_search_issues`     | Search issues with JQL                           |
| `jira_get_issue`         | Get a single issue by key/id                     |
| `jira_create_issue`      | Create an issue                                  |
| `jira_update_issue`      | Update fields on an issue                        |
| `jira_add_comment`       | Add a comment to an issue                        |
| `jira_list_transitions`  | List available workflow transitions              |
| `jira_transition_issue`  | Move an issue to a new status                    |
| `jira_list_projects`     | List / search projects                           |
| `jira_get_current_user`  | Get the authenticated user (incl. `accountId`)   |

### Confluence

| Tool                          | Description                             |
| ----------------------------- | --------------------------------------- |
| `confluence_search`           | Search content with CQL                 |
| `confluence_list_spaces`      | List spaces                             |
| `confluence_get_page`         | Get a page (with body)                  |
| `confluence_list_pages`       | List pages (optionally by space)        |
| `confluence_get_child_pages`  | List direct child pages                 |
| `confluence_create_page`      | Create a page (storage format body)     |
| `confluence_update_page`      | Update a page (requires new version)    |
| `confluence_delete_page`      | Delete a page                           |
| `confluence_get_page_comments`| List footer comments on a page          |
| `confluence_add_comment`      | Add a footer comment to a page          |

## Notes

- Jira rich-text fields (descriptions, comments) accept **plain text**, which is
  converted to Atlassian Document Format (ADF) automatically.
- Confluence page/comment bodies use **storage format** (XHTML), e.g. `<p>Hi</p>`.
- Your API token inherits all permissions of your account. Keep it secret and
  never commit it.