# Jira MCP Server

**For Claude Code CLI**

A Model Context Protocol (MCP) server that provides seamless Jira integration for Claude Code CLI.

## Features

- **Get Issue Details** - Fetch complete information about any Jira issue
- **Search Issues** - Query issues using JQL (Jira Query Language)
- **Get Comments** - Retrieve all comments on an issue
- **User Info** - Get authenticated user details
- **Multi-Environment Support** - Connect to multiple Jira instances simultaneously
- **Project-Specific Configuration** - Different Jira environments per project via `.mcp.json`

## Quick Start

### 1. Install

```bash
cd /var/home/mrwilde/mcp/jira-mcp-server
./install.sh
```

### 2. Configure (Per-Project)

Create `.mcp.json` in your project root:

```bash
cd /path/to/your/project

cat > .mcp.json <<'EOF'
{
  "mcpServers": {
    "jira": {
      "command": "python",
      "args": ["-m", "jira_mcp.server"],
      "env": {
        "JIRA_HOST": "https://your-company.atlassian.net",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_DEFAULT_PROJECT": "PROJ"
      }
    }
  }
}
EOF

# Don't commit tokens!
echo ".mcp.json" >> .gitignore
```

### 3. Verify

```bash
claude mcp list
```

### 4. Use

In Claude Code CLI, simply ask:
- "Get details for issue LXP-449"
- "Search for all my open tasks"
- "Show comments on PROJ-123"

## Installation & Configuration

See **[INSTALLATION.md](INSTALLATION.md)** for complete setup instructions including:
- System-wide installation
- Per-project configuration (`.mcp.json`)
- Global user configuration
- Multiple Jira environments
- CLI commands (`claude mcp add`)
- Security best practices

## Configuration Methods

### Method 1: Project `.mcp.json` File (Recommended)

```json
{
  "mcpServers": {
    "jira": {
      "command": "python",
      "args": ["-m", "jira_mcp.server"],
      "env": {
        "JIRA_HOST": "https://company.atlassian.net",
        "JIRA_EMAIL": "you@company.com",
        "JIRA_API_TOKEN": "your-token"
      }
    }
  }
}
```

### Method 2: Claude Code CLI Command

```bash
# Add to current project
cd /path/to/project
claude mcp add --scope project jira \
  --env JIRA_HOST=https://company.atlassian.net \
  --env JIRA_EMAIL=you@company.com \
  --env JIRA_API_TOKEN=your-token \
  -- python -m jira_mcp.server

# Add globally for all projects
claude mcp add --scope user jira \
  --env JIRA_HOST=https://company.atlassian.net \
  --env JIRA_EMAIL=you@company.com \
  --env JIRA_API_TOKEN=your-token \
  -- python -m jira_mcp.server
```

## Development

### Testing

```bash
# Test connection and authentication
source venv/bin/activate
python tests/test_connection.py

# Test with specific issue
python tests/test_connection.py LXP-449
```

### Project Structure

```
jira-mcp-server/
├── src/jira_mcp/
│   ├── server.py       # MCP server implementation
│   └── jira_client.py  # Jira API wrapper
├── tests/
│   └── test_connection.py
├── config-examples/    # Configuration templates
│   ├── project-mcp.json
│   └── multi-environment-mcp.json
├── pyproject.toml
├── requirements.txt
├── install.sh          # Quick install script
└── INSTALLATION.md     # Complete setup guide
```

## MCP Tools

### get_issue
Fetch detailed information about a Jira issue.

**Input:** `issue_key` (string) - e.g., "LXP-449"

**Returns:** Full issue details including summary, description, status, assignee, priority, dates, and project info.

### search_issues
Search for issues using JQL (Jira Query Language).

**Input:**
- `jql` (string) - Query string, e.g., "project = LXP AND status = 'To Do'"
- `max_results` (number, optional) - Default: 50

**Returns:** List of matching issues with key details.

### get_issue_comments
Get all comments on a specific issue.

**Input:** `issue_key` (string)

**Returns:** List of comments with author, body, and timestamps.

### get_current_user
Get information about the authenticated user.

**Input:** None

**Returns:** User details including username, email, and display name.

## JQL Query Examples

```
# All issues in a project
project = LXP

# Your open issues
assignee = currentUser() AND status != Done

# Recent updates
updated >= -7d ORDER BY updated DESC

# Complex query
project = LXP AND status = "In Progress" AND assignee = currentUser()
```

## Multiple Environments Example

```json
{
  "mcpServers": {
    "jira-prod": {
      "command": "python",
      "args": ["-m", "jira_mcp.server"],
      "env": {
        "JIRA_HOST": "https://prod.atlassian.net",
        "JIRA_EMAIL": "you@company.com",
        "JIRA_API_TOKEN": "prod-token",
        "JIRA_DEFAULT_PROJECT": "LXP"
      }
    },
    "jira-staging": {
      "command": "python",
      "args": ["-m", "jira_mcp.server"],
      "env": {
        "JIRA_HOST": "https://staging.atlassian.net",
        "JIRA_EMAIL": "you@company.com",
        "JIRA_API_TOKEN": "staging-token",
        "JIRA_DEFAULT_PROJECT": "LXL"
      }
    }
  }
}
```

## Claude Code CLI Commands

```bash
# List MCP servers
claude mcp list

# Get server details
claude mcp get jira

# Remove server
claude mcp remove --scope project jira

# Debug MCP issues
claude --mcp-debug
```

## Getting a Jira API Token

1. Visit: https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Name it (e.g., "MCP Server - Project X")
4. Copy the token immediately
5. Add it to your `.mcp.json`

## Security

- **Never commit tokens** to version control
- **Add `.mcp.json` to `.gitignore`** in every project
- Use project-specific tokens with minimal permissions
- Rotate tokens regularly (every 90 days)
- Revoke unused tokens
- Create `.mcp.json.example` templates for team onboarding

## Requirements

- Python >= 3.10
- Claude Code CLI
- Jira Cloud account with API access
- API token for authentication

## Dependencies

- `mcp` >= 1.0.0 - Model Context Protocol SDK
- `jira` >= 3.5.0 - Python Jira library
- `python-dotenv` >= 1.0.0 - Environment variable management
- `httpx` >= 0.27.0 - HTTP client

## Troubleshooting

### Module Not Found

Use full Python path in `.mcp.json`:

```json
{
  "mcpServers": {
    "jira": {
      "command": "/var/home/mrwilde/mcp/jira-mcp-server/venv/bin/python",
      "args": ["-m", "jira_mcp.server"],
      ...
    }
  }
}
```

### Check MCP Status

```bash
claude mcp list
claude --mcp-debug
```

See **[INSTALLATION.md](INSTALLATION.md)** for detailed troubleshooting.

## License

MIT

## Contributing

Contributions welcome! Please submit issues or pull requests.

## Support

- Check [INSTALLATION.md](INSTALLATION.md) for configuration help
- Review [CLAUDE.md](CLAUDE.md) for development guidance
- Open an issue on GitHub

## Changelog

### 0.1.0 (2025-10-28)
- Initial release for Claude Code CLI
- Core MCP server implementation
- Four essential Jira tools (get_issue, search_issues, get_issue_comments, get_current_user)
- Multi-environment support via `.mcp.json`
- Project-specific configuration
- Comprehensive documentation