Stéphane Tailland
90 lines
2.4 KiB
Markdown
90 lines
2.4 KiB
Markdown
# PM Backlog — MCP Atlassian Setup
|
|
|
|
This project connects Claude Code to Jira via the [mcp-atlassian](https://github.com/sooperset/mcp-atlassian) MCP server, running as a Docker container over streamable HTTP.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Claude Code → HTTP (localhost:9000/mcp) → Docker (mcp-atlassian) → Jira Cloud
|
|
```
|
|
|
|
The server uses the **streamable-http** transport (not stdio), which keeps the MCP server as a persistent process independent of Claude Code sessions.
|
|
|
|
## Prerequisites
|
|
|
|
- Docker and Docker Compose installed
|
|
- A Jira Cloud account with an API token ([generate one here](https://id.atlassian.com/manage-profile/security/api-tokens))
|
|
|
|
## Configuration
|
|
|
|
### Environment variables (`.env`)
|
|
|
|
| Variable | Description |
|
|
|---|---|
|
|
| `JIRA_URL` | Your Jira Cloud base URL (e.g. `https://your-org.atlassian.net`) |
|
|
| `JIRA_USERNAME` | Your Atlassian account email |
|
|
| `JIRA_API_TOKEN` | Your Atlassian API token |
|
|
|
|
OAuth2 variables are present but commented out — see the [OAuth2 section](#oauth2-future) below.
|
|
|
|
### Claude Code (`.mcp.json`)
|
|
|
|
Claude Code is configured to connect to the MCP server via:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"mcp-atlassian": {
|
|
"url": "http://localhost:9000/mcp"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
This file is picked up automatically when Claude Code is opened in this directory.
|
|
|
|
## Running the server
|
|
|
|
**Start:**
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
**Stop:**
|
|
```bash
|
|
docker compose down
|
|
```
|
|
|
|
**View logs:**
|
|
```bash
|
|
docker compose logs -f
|
|
```
|
|
|
|
**Update to the latest image:**
|
|
```bash
|
|
docker compose pull && docker compose up -d
|
|
```
|
|
|
|
The server listens on `http://localhost:9000/mcp`.
|
|
|
|
## OAuth2 (future)
|
|
|
|
The mcp-atlassian server has built-in OAuth2 proxy support. When you are ready to enable it:
|
|
|
|
1. Uncomment the `ATLASSIAN_OAUTH_*` variables in `.env` and fill in your OAuth2 app credentials (created in the [Atlassian developer console](https://developer.atlassian.com/console/myapps/)).
|
|
2. The server will expose standard OAuth2 discovery and token endpoints:
|
|
- `GET /.well-known/oauth-authorization-server`
|
|
- `POST /oauth/token`
|
|
- `POST /oauth/register`
|
|
3. Place a reverse proxy (nginx, Caddy, etc.) in front of port 9000 to enforce bearer token validation before forwarding requests to `/mcp`.
|
|
|
|
Clients then authenticate with:
|
|
```
|
|
Authorization: Bearer <user_oauth_access_token>
|
|
```
|
|
|
|
For multi-tenant deployments, per-user Jira identity can be passed via:
|
|
```
|
|
X-Atlassian-Cloud-Id: <user_cloud_id>
|
|
```
|