Content
# Jira MCP
Small Python MCP server for Jira Cloud.
## Prerequisite
- Python 3.10+ (the `mcp` package does not install on Python 3.9)
## Tool
- `get_jira_user`: fetches the authenticated Jira user via `/rest/api/3/myself`
- `get_current_active_sprint_info`: fetches the active sprint metadata from the configured project board (set via `JIRA_PROJECT_KEY` and `JIRA_BOARD_ID`)
- `get_active_sprint_stories`: fetches Story issues assigned to the current user from the active sprint on the configured board, excluding `Ready for Production` (includes subtasks by default)
- `get_my_assigned_board_stories`: backward-compatible alias of `get_active_sprint_stories`
- `get_all_current_sprint_stories`: fetches all Story issues from the active sprint on the configured board, excluding `Ready for Production` (includes subtasks by default)
- `move_story_to_in_progress`: transitions a Story from `Ready for Work` to `In Progress` with validation checks
- `create_subtask_for_parent_assignee`: creates a sub-task under a parent issue and assigns it to the same assignee as the parent issue
- `get_issue_attachments`: fetches attachment metadata (filename, mimeType, size, download URL, thumbnail) for a Jira issue; set `images_only=true` to return only screenshots/images
- `download_issue_attachments`: downloads an issue's attachments to a local directory (defaults to `tmp/{issue_key}/StoryAttachments/` relative to the current working directory); set `images_only=true` to download only images
## Environment
Set these variables before starting the server:
- `ATLASSIAN_SITE_URL` or `JIRA_SITE_URL` - Your Jira Cloud instance URL
- `ATLASSIAN_EMAIL` or `JIRA_EMAIL_ID` - Email for your Atlassian account
- `ATLASSIAN_API_TOKEN` or `JIRA_API_KEY` - API token (generate at https://id.atlassian.com/manage-profile/security/api-tokens)
- `JIRA_PROJECT_KEY` - Your Jira project key (e.g., `ABC` from issue `ABC-123`)
- `JIRA_BOARD_ID` - Your board ID (numeric, visible in board URL)
### How to create your Atlassian API token
1. Open: [https://id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Sign in with the same Atlassian account you use for Jira.
3. Click **Create API token**.
4. Enter a label (for example: `jira-mcp-local`) and create the token.
5. Copy the token value immediately (you may not be able to view it again).
6. Set it in your `.env` file:
```dotenv
JIRA_API_KEY="paste-your-token-here"
```
Security note: never commit `.env` or token values to Git.
### Finding Your Project Key and Board ID
**Project Key:**
- Open any issue in your project and look at the issue key: `PROJECT-123`
- The `PROJECT` part is your project key
- Or visit project settings and check the project details
**Board ID:**
- Open your Agile board in Jira
- The URL will contain `/board/{BOARD_ID}/`
- Example: `https://your-company.atlassian.net/software/c/projects/PROJECT/board/12345` → Board ID is `12345`
- Or use the Jira API: `curl -u email:token https://your-company.atlassian.net/rest/agile/1.0/board`
### Configuration (Default: `.env` file)
Use a local `.env` file as the primary setup method.
1. Copy the template:
```bash
cp .env.example .env
```
2. Edit `.env` with your Jira values:
```dotenv
JIRA_SITE_URL="https://your-company.atlassian.net"
JIRA_EMAIL_ID="your-email@company.com"
JIRA_API_KEY="your-api-token"
JIRA_PROJECT_KEY="YOUR_PROJECT_KEY"
JIRA_BOARD_ID="12345"
```
3. Start the server:
```bash
bash ./run.sh
```
`run.sh` automatically loads `.env` when present.
### Fallback options (only if needed)
You can also use exported shell variables (`~/.zshrc` / `~/.bashrc`) or inline exports, but `.env` is the default and recommended path for reliability.
## Run
From the project directory:
```bash
./run.sh
```
If your Mac only has Python 3.9, install a newer one first:
```bash
brew install python@3.11
```
Or:
```bash
python3 -m jira_mcp.server
```
## MCP Client Configuration (`mcp.json`)
When using this server from an MCP client (for example in VS Code), point the client to `run.sh`.
`run.sh` loads `.env` automatically, so keep your Jira credentials and project settings there.
1. Create `.env` from the template:
```bash
cp .env.example .env
```
2. Edit `.env` with your real values.
3. Update your `mcp.json` with a generic server entry like this (replace `/absolute/path/to/jira-mcp` with your local path):
```json
{
"servers": {
"JIRA_MCP_LOCAL": {
"type": "stdio",
"command": "bash",
"args": [
"/absolute/path/to/jira-mcp/run.sh"
]
}
},
"inputs": []
}
```
