# MCP Jira Server

A Model Context Protocol (MCP) server that integrates Jira with Claude Desktop, allowing you to fetch and view Jira issue details directly through Claude.

## Features

- 🔍 **Get Jira Issue Details**: Fetch comprehensive information about any Jira issue by its key
- 📁 **Browse Projects**: List projects and view project details
- 🧭 **Understand Workflows**: See issue types and statuses per project
- 🔎 **Search Issues (JQL)**: Flexible search with pagination and selected fields
- 📌 **Project Issue Lists**: Quickly list issues in a project
- 💬 **Issue Comments**: Read comments on an issue
- 🗂️ **Agile Views**: Boards, sprints, and sprint issue listings
- 🔐 **Secure Authentication**: Uses Jira API tokens for secure access
- 🎯 **Structured Data**: Returns both human-readable and structured JSON data
- 🚀 **Claude Desktop Integration**: Seamlessly works with Claude Desktop via MCP protocol

## Prerequisites

- Node.js (v18 or higher)
- Claude Desktop application
- Jira instance with API access
- Jira API token

## Installation

1. **Clone the repository**
   ```bash
   git clone https://github.com/imrnbeg/jira-mcp.git
   cd jira-mcp
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Build the project**
   ```bash
   npm run build
   ```

## Configuration

### 1. Create Environment File

Create a `.env` file in the project root with your Jira credentials:

```bash
# .env
JIRA_URL=https://yourcompany.atlassian.net
JIRA_EMAIL=your.email@company.com
JIRA_API_TOKEN=your_api_token_here
```

**How to get your Jira API token:**
1. Go to [Atlassian Account Settings](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 generated token

### 2. Update Server Path (Important!)

**⚠️ CRITICAL:** You must update the `.env` file path in the server code to match your system.

Edit `src/server.ts` and update line 8:

```typescript
// Change this path to match your system
loadEnvFile('/Users/imranbeg/mcp-get-server/.env');
```

**For different systems:**
- **macOS/Linux**: `/full/path/to/your/jira-mcp/.env`
- **Windows**: `C:\\full\\path\\to\\your\\jira-mcp\\.env`

### 3. Rebuild After Path Update

After updating the path, rebuild the project:

```bash
npm run build
```

## Claude Desktop Setup

### 1. Locate Claude Desktop Config

**macOS:**
```bash
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Windows:**
```bash
%APPDATA%\Claude\claude_desktop_config.json
```

### 2. Add MCP Server Configuration

Add this configuration to your Claude Desktop config file:

```json
{
  "mcpServers": {
    "mcp-jira-server": {
      "command": "node",
      "args": ["/full/path/to/your/jira-mcp/dist/server.js"],
      "cwd": "/full/path/to/your/jira-mcp"
    }
  }
}
```

**⚠️ Update the paths** to match your system:
- Replace `/full/path/to/your/jira-mcp` with your actual project path
- Use forward slashes (`/`) even on Windows

### 3. Restart Claude Desktop

After updating the configuration, completely quit and restart Claude Desktop.

## Usage

Once configured, you can use these example prompts in Claude Desktop:

### Basic Issue Lookup

```
Get details for Jira issue PROJ-123
```

```
Show me information about ticket TASK-456
```

```
What's the status of issue BUG-789?
```

### Detailed Issue Information

```
Get comprehensive details for Jira issue PROJ-123 including description, assignee, and priority
```

```
Show me the full details for ticket TASK-456 with all available information
```

### Multiple Issues

```
Get details for these Jira issues: PROJ-123, TASK-456, BUG-789
```

### Issue Status Check

```
What's the current status and assignee for issue PROJ-123?
```

```
Check the priority and due date for ticket TASK-456
```

## Available Tools

### `get_jira_issue`

Fetches detailed information about a Jira issue.

**Parameters:**
- `issueKey` (string): The Jira issue key (e.g., PROJ-123, TASK-456)

**Returns:**
- Issue summary, description, status, assignee, reporter
- Priority, issue type, creation and update dates
- Direct link to the issue in Jira
- Structured JSON data for programmatic access

### `list_jira_projects`

List accessible Jira projects with pagination and optional search query.

**Parameters:**
- `query` (string, optional): Search by key/name
- `startAt` (number, optional): Pagination start
- `maxResults` (number, optional): Page size (1-100)

### `get_jira_project`

Get full metadata for a Jira project by key or ID.

**Parameters:**
- `projectIdOrKey` (string): Project key or ID

### `get_project_statuses`

Get available statuses for each issue type in a project.

**Parameters:**
- `projectIdOrKey` (string): Project key or ID

### `search_jira_issues`

Search issues using JQL with pagination and field selection.

**Parameters:**
- `jql` (string): JQL query
- `startAt` (number, optional): Pagination start
- `maxResults` (number, optional): Page size (1-100)
- `fields` (string, optional): Comma-separated fields

### `list_project_issues`

List issues in a specific project with optional extra JQL.

**Parameters:**
- `projectKey` (string): Project key
- `jqlTail` (string, optional): Extra JQL (e.g., AND status="In Progress")
- `startAt` (number, optional): Pagination start
- `maxResults` (number, optional): Page size (1-100)

### `get_jira_issue_comments`

Retrieve comments for a Jira issue.

**Parameters:**
- `issueIdOrKey` (string): Issue key or ID
- `startAt` (number, optional): Pagination start
- `maxResults` (number, optional): Page size (1-100)

### `list_boards`

List Jira boards with optional filters.

**Parameters:**
- `type` ("scrum"|"kanban", optional): Board type
- `projectKeyOrId` (string, optional): Filter by project
- `startAt` (number, optional): Pagination start
- `maxResults` (number, optional): Page size (1-100)

### `list_board_sprints`

List sprints on a board.

**Parameters:**
- `boardId` (number): Board ID
- `state` ("active"|"future"|"closed", optional): Sprint state
- `startAt` (number, optional): Pagination start
- `maxResults` (number, optional): Page size (1-100)

### `list_sprint_issues`

List issues in a sprint with pagination.

**Parameters:**
- `sprintId` (number): Sprint ID
- `startAt` (number, optional): Pagination start
- `maxResults` (number, optional): Page size (1-100)
- `jql` (string, optional): Additional JQL filter

## Example Prompts

Use these prompts in Claude Desktop to leverage the tools:

### Project discovery
```
List my Jira projects.
```
```
Search Jira projects matching "platform".
```
```
Show details for project PROJ.
```
```
What issue types and statuses exist in project PROJ?
```

### Issue search and browsing
```
Find issues in project PROJ assigned to me that are In Progress.
```
```
Search issues updated in the last 7 days with label "release".
```
```
List issues in project PROJ with status = "To Do".
```
```
Get comments for issue PROJ-123.
```

### Agile views
```
List all Scrum boards for project PROJ.
```
```
Show active sprints on board 12.
```
```
List issues in sprint 345 ordered by priority.
```

## Development

### Running in Development Mode

```bash
npm run dev
```

### Building for Production

```bash
npm run build
```

### Type Checking

```bash
npm run typecheck
```

## Troubleshooting

### Server Not Loading Environment Variables

1. **Check the path in `src/server.ts`** - Make sure it points to your actual `.env` file location
2. **Rebuild the project** after changing the path:
   ```bash
   npm run build
   ```
3. **Verify `.env` file exists** and contains valid credentials

### Claude Desktop Not Connecting

1. **Check the config file paths** - Ensure all paths in `claude_desktop_config.json` are correct
2. **Restart Claude Desktop** completely
3. **Check Claude Desktop logs** for connection errors

### Jira API Errors

1. **Verify your API token** is valid and not expired
2. **Check your Jira URL** format (should include `https://`)
3. **Ensure your account** has access to the Jira instance

## Project Structure

```
jira-mcp/
├── src/
│   ├── server.ts          # Main MCP server implementation
│   └── load-env.ts        # Custom environment loader
├── dist/                  # Compiled JavaScript files
├── .env                   # Environment variables (create this)
├── package.json           # Dependencies and scripts
├── tsconfig.json          # TypeScript configuration
└── README.md              # This file
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

## License

ISC License

## Support

For issues and questions:
1. Check the troubleshooting section above
2. Review the [MCP documentation](https://modelcontextprotocol.io/)
3. Open an issue on GitHub

---

**Happy Jira integration with Claude! 🚀**