# Jira Mcp Server

> MCP server for Jira integration with AI assistants

- **Type:** MCP server
- **Install:** `agentstack add mcp-sthirugn-jira-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [sthirugn](https://agentstack.voostack.com/s/sthirugn)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [sthirugn](https://github.com/sthirugn)
- **Source:** https://github.com/sthirugn/jira-mcp-server

## Install

```sh
agentstack add mcp-sthirugn-jira-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Jira MCP Server

A clean and focused Model Context Protocol (MCP) server that provides seamless integration between AI assistants and Jira, enabling natural language interaction with your Jira projects, issues, and workflows.

## 🎯 Features

- **11 Comprehensive Tools** for full Jira interaction
- **Natural Language Interface** - Ask AI to manage your Jira work
- **Real-time Updates** - Get current project status and issue information
- **Secure Authentication** - API token-based authentication
- **Cross-platform** - Works with any MCP-compatible client
- **Easy Setup** - Simple configuration and testing

## 🛠️ Available Tools

| Tool | Description | Example Usage |
|------|-------------|---------------|
| `get_issue` | Get detailed issue info | `get_issue(issue_key="PROJ-12345")` |
| `search_issues` | Search with JQL | `search_issues(jql="project = PROJ")` |
| `create_issue` | Create new issue | `create_issue(project_key="PROJ", issue_type="Bug", summary="...")` |
| `update_issue` | Update existing issue | `update_issue(issue_key="PROJ-12345", summary="New title")` |
| `add_comment` | Add comment to issue | `add_comment(issue_key="PROJ-12345", comment="...")` |
| `get_comments` | Get all comments | `get_comments(issue_key="PROJ-12345")` |
| `transition_issue` | Move through workflow | `transition_issue(issue_key="PROJ-12345", transition_name="In Progress")` |
| `get_project` | Get project info | `get_project(project_key="PROJ")` |
| `get_issue_types` | Get available types | `get_issue_types(project_key="PROJ")` |
| `get_my_issues` | Get assigned issues | `get_my_issues(max_results=20)` |
| `get_project_issues` | Get project issues | `get_project_issues(project_key="PROJ")` |

## 🚀 Quick Start (5 minutes)

### Prerequisites

- Python 3.8 or higher
- Jira account with API access
- MCP-compatible client (Cursor, VS Code, etc.)

### 1. Clone and Setup

```bash
cd jira-mcp-server
pip install -r requirements.txt
```

### 2. Configure Credentials

Create a `.env` file with your Jira details:

```bash
JIRA_SERVER=https://your-company.atlassian.net
JIRA_EMAIL=your-email@company.com
JIRA_API_TOKEN=your-api-token
```

**Getting Your API Token:**
1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Copy the token to your `.env` file

### 3. Test Connection

```bash
python3 test_connection.py
```

### 4. Configure MCP Client

#### For Cursor:
Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "jira": {
      "type": "stdio",
      "command": "python3",
      "args": ["/full/path/to/jira-mcp-server/server.py"],
      "env": {
        "JIRA_SERVER": "https://your-company.atlassian.net",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

#### For VS Code:
Add to your VS Code MCP configuration:

```json
{
  "mcpServers": {
    "jira": {
      "type": "stdio",
      "command": "python3",
      "args": ["/full/path/to/jira-mcp-server/server.py"],
      "env": {
        "JIRA_SERVER": "https://your-company.atlassian.net",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

**Important:** 
- Use the full absolute path to `server.py`!
- The `"type": "stdio"` field is **required** for proper MCP communication
- If using a virtual environment, use the full path to the Python interpreter: `"/path/to/venv/bin/python3"`

### 5. Start the Server

```bash
python3 server.py
```

### 6. Restart and Test

Restart your MCP client and try these commands:

- "Show me all open issues in project XYZ"
- "Create a new task for fixing the login bug"
- "Search for high priority bugs assigned to me"

## 📁 Project Structure

```
jira-mcp-server/
├── server.py              # Main MCP server implementation
├── test_connection.py     # Connection test script
├── requirements.txt       # Python dependencies
├── .env                   # Environment variables (create this)
└── README.md              # This file
```

## 🔗 Related Projects

- **[Jira Weekly Reports](https://github.com/sthirugn/jira-weekly-reports)** - Generate automated weekly team summaries from Jira tickets

## 🎯 Usage Examples

### Get Your Issues
```python
# Get issues assigned to you
get_my_issues(max_results=10)
```

### Search for Specific Issues
```python
# Find high priority bugs
search_issues(jql="project = PROJ AND priority = High AND type = Bug")

# Find recent updates
search_issues(jql="project = PROJ AND updated >= -7d")
```

### Create New Issue
```python
create_issue(
    project_key="PROJ",
    issue_type="Task",
    summary="Implement new feature",
    description="Add support for advanced filtering",
    priority="Medium"
)
```

### Update Issue Status
```python
transition_issue(
    issue_key="PROJ-12345",
    transition_name="In Progress"
)
```

### Get Issue Details
```python
# Get details for issue PROJ-12345
get_issue(issue_key="PROJ-12345")
```

### Search Issues
```python
# Search for open issues in PROJ project
search_issues(jql="project = PROJ AND status = Open", max_results=10)
```

## 🔍 JQL Query Examples

### Common Patterns
```jql
# Your assigned issues
assignee = currentUser()

# Issues in specific project
project = PROJ

# Open issues
status = Open

# Issues updated in last 7 days
updated >= -7d

# High priority issues
priority = High

# Issues with specific component
component = "Backend"

# Status filters
status IN ("In Progress", "Code Review")

# Date filters
created >= "2025-01-01"

# Priority filters
priority IN ("High", "Critical")

# Combined queries
project = PROJ AND status = Open AND priority = High
assignee = currentUser() AND updated >= -3d
```

## 🧪 Testing Your Setup

### 1. Connection Test
```bash
python3 test_connection.py
```
✅ Should show: "Successfully connected to Jira"

### 2. Start Server (Optional Test)
```bash
python3 server.py
```
✅ Should start the MCP server and wait for connections.

### 3. Individual Tool Test
```bash
# Test search functionality
python3 -c "
import asyncio
from server import JiraMCPServer

async def test():
    server = JiraMCPServer()
    await server._init_jira_client()
    result = await server._search_issues('project = PROJ', max_results=3)
    print(f'Found {len(result)} results')

asyncio.run(test())
"
```

## 🚀 Starting the Server

Simply run the server directly:

```bash
python3 server.py
```

**Note:** Make sure you've completed the setup steps above (installing dependencies, creating `.env` file, and testing connection) before starting the server.

## 🔒 Security Best Practices

1. **Never commit `.env` file** - Add to `.gitignore`
2. **Use API tokens** instead of passwords
3. **Rotate tokens regularly**
4. **Limit token permissions** to minimum required
5. **Use environment variables** for sensitive data

## 🐛 Troubleshooting

### Common Issues

1. **Authentication Error**
   - Check your API token is correct
   - Ensure your email matches your Jira account
   - Verify token hasn't expired

2. **Connection Error**
   - Check your internet connection
   - Verify JIRA_SERVER URL is correct
   - Ensure firewall allows HTTPS connections

3. **Permission Error**
   - Check your Jira permissions
   - Verify you have access to the project/issue
   - Contact your Jira administrator

4. **"Permission denied" errors**
   - Run: `chmod +x server.py test_connection.py`

5. **"Module not found" errors**
   - Run: `pip install -r requirements.txt`

6. **Cursor doesn't see the server**
   - Double-check the absolute path in your MCP config
   - Restart Cursor completely
   - Check that the `.env` file has the correct credentials
   - **"No tools or prompts" error**: Ensure `"type": "stdio"` is included in your MCP configuration
   - **Virtual environment**: Use the full path to your Python interpreter (e.g., `/path/to/venv/bin/python3`)

### Debug Mode

Enable debug logging by modifying the logging level in `server.py`:

```python
logging.basicConfig(level=logging.DEBUG)
```

## 🛠️ Development

### Adding New Tools

1. Add tool definition to `list_tools()` method
2. Add handler in `call_tool()` method
3. Implement the actual tool method
4. Update this README

### Error Handling

The server includes comprehensive error handling:
- Connection errors
- Authentication failures
- Invalid issue keys
- JQL syntax errors
- Permission errors

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## 🎉 Success!

Your Jira MCP server is now properly configured and ready to use! You can:

- ✅ Search and view Jira issues
- ✅ Create and update issues
- ✅ Manage comments and transitions
- ✅ Get project information
- ✅ Handle your assigned work

The server provides a powerful interface between AI assistants and your Jira workflow, making it easier to manage projects and track progress.

## 📈 What's Next?

Once it's working, you can:
- Ask about specific issues: "What's the status of PROJ-123?"
- Create issues: "Create a bug report for the navbar not working"
- Search with JQL: "Find all issues in project ABC that are in review"
- Add comments: "Add a comment to PROJ-456 saying testing is complete"
- Transition issues: "Move PROJ-789 to Done"

Enjoy your new Jira integration! 🎉

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [sthirugn](https://github.com/sthirugn)
- **Source:** [sthirugn/jira-mcp-server](https://github.com/sthirugn/jira-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-sthirugn-jira-mcp-server
- Seller: https://agentstack.voostack.com/s/sthirugn
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.