Content
# mcp-atlassian
A Model Context Protocol (MCP) server in Go that provides tools for interacting with Jira and Confluence Cloud.
## Features
### Jira Tools
| Tool | Description |
|------|-------------|
| `jira_search` | Search issues using JQL |
| `jira_get_issue` | Get issue details by key |
| `jira_create_issue` | Create a new issue |
| `jira_update_issue` | Update issue fields |
| `jira_delete_issue` | Delete an issue |
| `jira_get_transitions` | Get available status transitions |
| `jira_transition_issue` | Transition issue to new status |
| `jira_add_comment` | Add a comment to an issue |
| `jira_get_comments` | Get comments on an issue |
| `jira_list_projects` | List accessible projects |
| `jira_get_create_metadata` | Get metadata for creating issues (required fields, allowed values) |
| `jira_get_edit_metadata` | Get metadata for editing an issue (editable fields, allowed values) |
| `jira_get_transition_metadata` | Get transition metadata (available transitions with field requirements) |
| `jira_api_request` | Make generic HTTP requests to any Jira API endpoint (v3 or Agile API) |
### Confluence Tools
| Tool | Description |
|------|-------------|
| `confluence_search` | Search content using CQL |
| `confluence_get_page` | Get page by ID |
| `confluence_get_page_by_title` | Get page by space key + title |
| `confluence_create_page` | Create a new page |
| `confluence_update_page` | Update an existing page |
| `confluence_delete_page` | Delete a page |
| `confluence_get_children` | Get child pages |
| `confluence_get_comments` | Get page comments |
| `confluence_add_comment` | Add a comment to a page |
| `confluence_api_request` | Make generic HTTP requests to any Confluence API endpoint (v1 or v2) |
## Using Generic API Request Tools
The `jira_api_request` and `confluence_api_request` tools provide direct access to any Jira or Confluence REST API endpoint. These are useful for operations not covered by specific tools.
### Examples
**Get Jira board with active sprints:**
```json
{
"method": "GET",
"endpoint": "/rest/agile/1.0/board/123"
}
```
**Get active sprints for a board:**
```json
{
"method": "GET",
"endpoint": "/rest/agile/1.0/board/123/sprint?state=active"
}
```
**Get issues in a sprint:**
```json
{
"method": "GET",
"endpoint": "/rest/agile/1.0/sprint/456/issue"
}
```
**List Confluence spaces:**
```json
{
"method": "GET",
"endpoint": "/rest/api/space"
}
```
**Get space details:**
```json
{
"method": "GET",
"endpoint": "/rest/api/space/DEV?expand=description.view,homepage"
}
```
See the official documentation for available endpoints:
- [Jira REST API v3](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/)
- [Jira Agile REST API](https://developer.atlassian.com/cloud/jira/software/rest/intro/)
- [Confluence REST API v1](https://developer.atlassian.com/cloud/confluence/rest/v1/intro/)
- [Confluence REST API v2](https://developer.atlassian.com/cloud/confluence/rest/v2/intro/)
## Configuration
Configuration is loaded from environment variables (with optional `.env` file support).
### Quick start (both Jira and Confluence on the same site)
```bash
export ATLASSIAN_URL=https://yoursite.atlassian.net
export ATLASSIAN_USER=you@example.com
export ATLASSIAN_TOKEN=your-api-token
```
This automatically configures:
- **Jira** at `ATLASSIAN_URL`
- **Confluence** at `ATLASSIAN_URL/wiki`
### Per-product overrides
Product-specific variables always win when set (even if empty). An empty URL disables that integration.
| Variable | Fallback | Description |
|----------|----------|-------------|
| `JIRA_URL` | `ATLASSIAN_URL` | Jira base URL |
| `JIRA_USER` | `ATLASSIAN_USER` | Jira user (email) |
| `JIRA_TOKEN` | `ATLASSIAN_TOKEN` | Jira API token |
| `CONFLUENCE_URL` | `ATLASSIAN_URL/wiki` | Confluence base URL |
| `CONFLUENCE_USER` | `ATLASSIAN_USER` | Confluence user (email) |
| `CONFLUENCE_TOKEN` | `ATLASSIAN_TOKEN` | Confluence API token |
### Server settings
| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_TRANSPORT` | `stdio` | Transport mode: `stdio` or `sse` |
| `MCP_SSE_ADDR` | `:8080` | Listen address for SSE mode |
### Examples
Disable Confluence (Jira only):
```bash
export ATLASSIAN_URL=https://yoursite.atlassian.net
export ATLASSIAN_USER=you@example.com
export ATLASSIAN_TOKEN=your-api-token
export CONFLUENCE_URL=
```
Separate credentials per product:
```bash
export JIRA_URL=https://jira.example.com
export JIRA_USER=jira-user@example.com
export JIRA_TOKEN=jira-token
export CONFLUENCE_URL=https://wiki.example.com/wiki
export CONFLUENCE_USER=wiki-user@example.com
export CONFLUENCE_TOKEN=wiki-token
```
## Build & Run
### From source
```bash
go build -o mcp-atlassian .
# stdio mode (default)
./mcp-atlassian
# SSE mode
MCP_TRANSPORT=sse MCP_SSE_ADDR=:9090 ./mcp-atlassian
```
### Docker
Pull the pre-built image from GHCR:
```bash
docker pull ghcr.io/ns-wsuen/mcp-atlassian:main
```
Run with stdio (for MCP clients):
```bash
docker run --rm -i \
-e ATLASSIAN_URL=https://yoursite.atlassian.net \
-e ATLASSIAN_USER=you@example.com \
-e ATLASSIAN_TOKEN=your-api-token \
ghcr.io/ns-wsuen/mcp-atlassian:main
```
Run with SSE:
```bash
docker run --rm -p 8080:8080 \
-e ATLASSIAN_URL=https://yoursite.atlassian.net \
-e ATLASSIAN_USER=you@example.com \
-e ATLASSIAN_TOKEN=your-api-token \
-e MCP_TRANSPORT=sse \
ghcr.io/ns-wsuen/mcp-atlassian:main
```
Build the image locally:
```bash
docker build -t mcp-atlassian .
```
The image uses a multi-stage build with a `scratch` base — the final image is ~8 MB.
## Usage with MCP Clients
### Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"atlassian": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "ATLASSIAN_URL",
"-e", "ATLASSIAN_USER",
"-e", "ATLASSIAN_TOKEN",
"ghcr.io/ns-wsuen/mcp-atlassian:main"
],
"env": {
"ATLASSIAN_URL": "https://yoursite.atlassian.net",
"ATLASSIAN_USER": "you@example.com",
"ATLASSIAN_TOKEN": "your-api-token"
}
}
}
}
```
### OpenCode
Add to your `opencode.json`:
```json
{
"mcp": {
"atlassian": {
"type": "local",
"environment": {
"ATLASSIAN_URL": "https://yoursite.atlassian.net",
"ATLASSIAN_USER": "you@example.com",
"ATLASSIAN_TOKEN": "your-api-token"
},
"command": [
"docker",
"run", "--rm", "-i",
"-e", "ATLASSIAN_URL",
"-e", "ATLASSIAN_USER",
"-e", "ATLASSIAN_TOKEN",
"ghcr.io/ns-wsuen/mcp-atlassian:main"
]
}
}
}
```
### Local binary
```json
{
"mcpServers": {
"atlassian": {
"command": "/path/to/mcp-atlassian",
"env": {
"ATLASSIAN_URL": "https://yoursite.atlassian.net",
"ATLASSIAN_USER": "you@example.com",
"ATLASSIAN_TOKEN": "your-api-token"
}
}
}
}
```
## Project Structure
```
.
├── main.go # Entry point (stdio + SSE transport)
├── Dockerfile # Multi-stage build (scratch base, ~8 MB)
├── .github/workflows/docker.yml # CI: build and push to GHCR
├── internal/
│ ├── config/config.go # Environment variable loading
│ ├── atlassian/client.go # Base HTTP client with basic auth
│ ├── jira/client.go # Jira REST API v3 client
│ ├── confluence/client.go # Confluence REST API client
│ └── server/
│ ├── server.go # MCP server factory
│ ├── jira_tools.go # Jira MCP tool registrations
│ └── confluence_tools.go # Confluence MCP tool registrations
├── go.mod
└── .env.example
```
