{"_id":"@devpuccino/mcp-jira","name":"@devpuccino/mcp-jira","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@devpuccino/mcp-jira","version":"1.0.0","description":"MCP Server for Jira API - Connect Claude to Jira with Model Context Protocol","main":"index.js","type":"module","bin":{"mcp-jira":"dist/index.js"},"scripts":{"build":"tsc && chmod 755 dist/index.js","prepare":"npm run build","test":"jest","test:coverage":"jest --coverage","lint":"tsc --noEmit","test:integration":"jest integration.test.ts --runInBand"},"repository":{"type":"git","url":"git+ssh://git@bitbucket.org/devpuccino/mcp-jira.git"},"keywords":["mcp","modelcontextprotocol","jira","atlassian","issue-tracking","api","mcp-server"],"author":{"name":"DevPuccino","email":"devpuccino@example.com","url":"https://github.com/devpuccino"},"license":"ISC","bugs":{"url":"https://bitbucket.org/devpuccino/mcp-jira/issues"},"homepage":"https://bitbucket.org/devpuccino/mcp-jira#readme","dependencies":{"@modelcontextprotocol/sdk":"^1.27.1","axios":"^1.13.6","commander":"^14.0.3","zod":"^4.3.6"},"devDependencies":{"@types/commander":"^2.12.0","@types/jest":"^30.0.0","@types/node":"^25.3.5","jest":"^30.2.0","ts-jest":"^29.4.6","typescript":"^5.9.3"},"gitHead":"b6f9abe68fcd58d32cb2151a62cb130a8c74e128","_id":"@devpuccino/mcp-jira@1.0.0","_nodeVersion":"25.8.0","_npmVersion":"11.11.0","dist":{"integrity":"sha512-50IYztb/VX70t/yqOEsT1/dvJaaeecIhJyiMEcXATU+nzV4GayS5ZieTA72Yv5tETwpcUhuUjeM3HixjLin3aQ==","shasum":"e06b6ca8fadd6293bae3a78a7d5ef0fa5b28e2b6","tarball":"https://registry.npmjs.org/@devpuccino/mcp-jira/-/mcp-jira-1.0.0.tgz","fileCount":167,"unpackedSize":244019,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIC26XBjT/4t5DiVw/QX9gYvNa7x3nDpg9c7z+cw7QXDtAiEAjXGPa6LrOlbHi6SN5K+flRM6gZiYA5WHE5Kd3uaCweM="}]},"_npmUser":{"name":"devpuccino","email":"janepop.ati@gmail.com"},"directories":{},"maintainers":[{"name":"devpuccino","email":"janepop.ati@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-jira_1.0.0_1773030335765_0.197963757853713"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-09T04:25:35.703Z","1.0.0":"2026-03-09T04:25:35.913Z","modified":"2026-03-09T04:25:36.078Z"},"maintainers":[{"name":"devpuccino","email":"janepop.ati@gmail.com"}],"description":"MCP Server for Jira API - Connect Claude to Jira with Model Context Protocol","homepage":"https://bitbucket.org/devpuccino/mcp-jira#readme","keywords":["mcp","modelcontextprotocol","jira","atlassian","issue-tracking","api","mcp-server"],"repository":{"type":"git","url":"git+ssh://git@bitbucket.org/devpuccino/mcp-jira.git"},"author":{"name":"DevPuccino","email":"devpuccino@example.com","url":"https://github.com/devpuccino"},"bugs":{"url":"https://bitbucket.org/devpuccino/mcp-jira/issues"},"license":"ISC","readme":"# @devpuccino/mcp-jira\n\n[![npm version](https://badge.fury.io/js/@devpuccino%2Fmcp-jira.svg)](https://www.npmjs.com/package/@devpuccino/mcp-jira)\n[![npm downloads](https://img.shields.io/npm/dm/@devpuccino/mcp-jira.svg)](https://npmjs.com/package/@devpuccino/mcp-jira)\n[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)\n\n> **Connect Claude to Jira with Model Context Protocol (MCP)** - Create issues, search, add comments, and automate your workflow with AI assistance.\n\n---\n\n## 🚀 Quick Start\n\n### **Option 1: Use with npx (Recommended)**\n\n```bash\n# No installation needed!\nnpx @devpuccino/mcp-jira --list-tools\n```\n\n### **Option 2: Install Globally**\n\n```bash\nnpm install -g @devpuccino/mcp-jira\nmcp-jira --list-tools\n```\n\n### **Option 3: Use with Claude Desktop** ⭐\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"jira\": {\n      \"command\": \"npx\",\n      \"args\": [\"@devpuccino/mcp-jira\"],\n      \"env\": {\n        \"JIRA_BASE_URL\": \"https://your-domain.atlassian.net\",\n        \"JIRA_EMAIL\": \"your-email@example.com\",\n        \"JIRA_TOKEN\": \"your-api-token\"\n      }\n    }\n  }\n}\n```\n\nThen restart Claude Desktop and start chatting! 🎉\n\n---\n\n## ✨ Features\n\n- **32 MCP Tools** - Full Jira API coverage\n- **10 Tool Categories** - Organized for easy access\n- **Selective Tool Loading** - Save tokens by loading only what you need\n- **MCP Standard Compliant** - 100% compliance score\n- **ADF Format Support** - Automatic plain text to ADF conversion\n- **CLI & MCP Modes** - Use standalone or with AI assistants\n- **Optimized Package Size** - Only 37 KB (gzipped)\n\n---\n\n## 🔧 Installation\n\n### **Global Installation**\n\n```bash\nnpm install -g @devpuccino/mcp-jira\n```\n\n### **Verify Installation**\n\n```bash\nmcp-jira --list-tools\n```\n\n---\n\n## 📖 Usage Examples\n\n### **1. Standalone CLI Mode**\n\n#### **List Available Tools**\n\n```bash\nmcp-jira --list-tools\n```\n\n**Output:**\n```\nAvailable tools:\n  - get-fields\n  - get-field-by-key\n  - create-field\n  - get-projects\n  - get-project-by-key\n  - create-issue\n  - get-issue\n  - update-issue\n  - delete-issue\n  - search-issues\n  - get-comments\n  - add-comment\n  ... (22 more)\n```\n\n#### **List Categories**\n\n```bash\nmcp-jira --list-categories\n```\n\n**Output:**\n```\nAvailable categories:\n  - fields\n  - projects\n  - issues\n  - comments\n  - transitions\n  - attachments\n  - worklogs\n  - status\n  - metadata\n  - properties\n```\n\n---\n\n### **2. Selective Tool Loading** (Save Tokens! 💰)\n\nLoad only the tools you need to reduce token usage by up to 95%!\n\n#### **Load Specific Tools**\n\n```bash\n# Load only issue operations\nmcp-jira --tools=get-issue,create-issue,search-issues\n\n# Load by category (7 tools, saves 78% tokens)\nmcp-jira --categories=issues,comments\n\n# Developer daily driver (12 tools)\nmcp-jira --categories=issues,comments,attachments,transitions\n```\n\n#### **Exclude Destructive Operations**\n\n```bash\n# Read-only mode (no delete operations)\nmcp-jira --exclude=delete-issue,delete-attachment,delete-worklog-by-id\n```\n\n#### **Minimal Setup** (2 tools, saves 94% tokens)\n\n```bash\nmcp-jira --tools=get-issue,search-issues\n```\n\n---\n\n### **3. With Claude Desktop** 🤖\n\n#### **Basic Configuration**\n\n```json\n{\n  \"mcpServers\": {\n    \"jira\": {\n      \"command\": \"npx\",\n      \"args\": [\"@devpuccino/mcp-jira\"],\n      \"env\": {\n        \"JIRA_BASE_URL\": \"https://your-domain.atlassian.net\",\n        \"JIRA_EMAIL\": \"your-email@example.com\",\n        \"JIRA_TOKEN\": \"your-api-token\"\n      }\n    }\n  }\n}\n```\n\n#### **Load Specific Tools Only**\n\n```json\n{\n  \"mcpServers\": {\n    \"jira\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"@devpuccino/mcp-jira\",\n        \"--categories=issues,comments\"\n      ],\n      \"env\": {\n        \"JIRA_BASE_URL\": \"https://your-domain.atlassian.net\",\n        \"JIRA_EMAIL\": \"your-email@example.com\",\n        \"JIRA_TOKEN\": \"your-api-token\"\n      }\n    }\n  }\n}\n```\n\n#### **Example Interaction**\n\n**You:**\n> \"Create a new task in PROJ project for adding login feature with high priority\"\n\n**Claude (using mcp-jira):**\n> ✅ Created issue PROJ-123: \"Add login feature\"\n> - Type: Task\n> - Priority: High\n> - Status: To Do\n\n---\n\n**You:**\n> \"Search for all open bugs in PROJ project assigned to me\"\n\n**Claude (using mcp-jira):**\n> Found 3 open bugs:\n> - PROJ-45: Login button not working\n> - PROJ-67: Password reset fails\n> - PROJ-89: Session timeout issue\n\n---\n\n**You:**\n> \"Add a comment to PROJ-45 saying we're investigating the issue\"\n\n**Claude (using mcp-jira):**\n> ✅ Comment added to PROJ-45:\n> \"We're investigating the issue and will update soon.\"\n\n---\n\n### **4. Development Setup**\n\n#### **Using with Specific Tools**\n\n```bash\n# For bug triage workflow\nmcp-jira --tools=get-issue,search-issues,add-comment,transition-issue\n\n# For time tracking\nmcp-jira --categories=worklogs,issues\n\n# For project management\nmcp-jira --categories=projects,issues,status\n```\n\n---\n\n## 🔐 Environment Variables\n\n### **Required**\n\nSet these before running:\n\n```bash\nexport JIRA_BASE_URL=\"https://your-domain.atlassian.net\"\nexport JIRA_EMAIL=\"your-email@example.com\"\nexport JIRA_TOKEN=\"your-api-token\"\n```\n\n### **Getting Your Jira API Token**\n\n1. Go to: https://id.atlassian.com/manage-profile/security/api-tokens\n2. Click **Create API token**\n3. Give it a label (e.g., \"MCP Server\")\n4. Copy the token\n5. Use it in the environment variable\n\n### **Finding Your Jira Domain**\n\nYour Jira domain is in the URL:\n```\nhttps://your-domain.atlassian.net\n                ↑\n           This part\n```\n\nExample: If your URL is `https://devpuccino.atlassian.net`, then:\n```bash\nexport JIRA_BASE_URL=\"https://devpuccino.atlassian.net\"\n```\n\n---\n\n## 🛠️ Available Tools\n\n### **Issues (5 tools)**\n- `create-issue` - Create new issues\n- `get-issue` - Get issue details\n- `update-issue` - Update issue fields\n- `delete-issue` - Delete issues (use carefully!)\n- `search-issues` - Search with JQL queries\n\n### **Comments (2 tools)**\n- `get-comments` - List issue comments\n- `add-comment` - Add comment to issue\n\n### **Projects (2 tools)**\n- `get-projects` - List all projects\n- `get-project-by-key` - Get project details\n\n### **Attachments (3 tools)**\n- `get-attachments` - List attachments\n- `post-attachments` - Upload files\n- `delete-attachment` - Remove attachments\n\n### **Worklogs (5 tools)**\n- `get-worklog` - List worklogs\n- `post-worklog` - Log time\n- `get-worklog-by-id` - Get specific worklog\n- `update-worklog` - Update worklog\n- `delete-worklog-by-id` - Delete worklog\n\n### **And More...**\n\n- **Fields** (3 tools) - Custom field management\n- **Transitions** (2 tools) - Workflow transitions\n- **Status** (2 tools) - Status information\n- **Metadata** (4 tools) - Edit metadata, watchers\n- **Properties** (4 tools) - Issue properties\n\n**Total:** 32 tools across 10 categories\n\n---\n\n## 💡 Common Use Cases\n\n### **1. Daily Standup**\n\n```bash\n# Load tools for status updates\nmcp-jira --categories=issues,comments\n```\n\n**Ask Claude:**\n> \"What issues are assigned to me that were updated yesterday?\"\n\n### **2. Sprint Planning**\n\n```bash\n# Load tools for backlog management\nmcp-jira --categories=issues,comments,worklogs\n```\n\n**Ask Claude:**\n> \"Show me all unresolved issues in PROJ project sorted by priority\"\n\n### **3. Code Review**\n\n```bash\n# Load tools for review workflow\nmcp-jira --tools=get-issue,search-issues,add-comment,transition-issue\n```\n\n**Ask Claude:**\n> \"Move PROJ-123 to 'In Review' and add a comment that PR is ready\"\n\n### **4. Time Tracking**\n\n```bash\n# Load time tracking tools\nmcp-jira --categories=worklogs\n```\n\n**Ask Claude:**\n> \"Log 2 hours on PROJ-45 for today with comment 'Fixed login bug'\"\n\n---\n\n## 📊 Token Optimization\n\nLoad only what you need to save tokens:\n\n| Configuration | Tools | Token Usage | Use Case |\n|---------------|-------|-------------|----------|\n| All Tools | 32 | 100% | Full access |\n| Issues + Comments | 7 | ~22% | Daily development |\n| Minimal | 2 | ~6% | Read-only queries |\n| Developer Daily | 12 | ~37% | Regular workflow |\n\n**Example:**\n```bash\n# Save 78% tokens for simple workflows\nmcp-jira --categories=issues,comments\n```\n\n---\n\n## 🔒 Security Best Practices\n\n### **1. Use Environment Variables**\n\n```bash\n# ✅ Good\nexport JIRA_TOKEN=\"your-token\"\nmcp-jira\n\n# ❌ Bad - Don't hardcode tokens!\n# Edit source code with token inside\n```\n\n### **2. Use .env File (Development)**\n\nCreate `.env` file:\n```bash\nJIRA_BASE_URL=https://your-domain.atlassian.net\nJIRA_EMAIL=your-email@example.com\nJIRA_TOKEN=your-api-token\n```\n\nThen load with:\n```bash\nset -a && source .env && set +a && mcp-jira\n```\n\n### **3. Never Commit Tokens**\n\nAdd to `.gitignore`:\n```bash\n.env\n*.pem\n*.key\n```\n\n---\n\n## 🧪 Development\n\n### **Build from Source**\n\n```bash\ngit clone https://bitbucket.org/devpuccino/mcp-jira.git\ncd mcp-jira\nnpm install\nnpm run build\n```\n\n### **Run Tests**\n\n```bash\n# Unit tests\nnpm test\n\n# Coverage report\nnpm run test:coverage\n\n# MCP compliance check\nnode scripts/check-mcp-standard.js\n```\n\n### **CLI Tests**\n\n```bash\nbash scripts/test-npx-cli.sh\n```\n\n---\n\n## 📚 Documentation\n\n- [CLI Usage Guide](docs/cli-usage.md) - Command-line options\n- [Tool Selection Guide](docs/TOOL-SELECTION-GUIDE.md) - Optimize tool loading\n- [MCP Architecture](docs/MCP-ARCHITECTURE.md) - How MCP works\n- [Jira API Reference](docs/JIRA-API-REFERENCE.md) - API details\n- [ADF Format Guide](docs/ADF-FIELDS.md) - Working with ADF format\n\n---\n\n## 🆘 Troubleshooting\n\n### **\"Command not found: mcp-jira\"**\n\n```bash\n# Check installation\nnpm list -g @devpuccino/mcp-jira\n\n# Reinstall if needed\nnpm install -g @devpuccino/mcp-jira\n```\n\n### **\"Authentication failed\"**\n\n```bash\n# Verify environment variables\necho $JIRA_EMAIL\necho $JIRA_BASE_URL\n\n# Test token\ncurl -u your-email:your-token \\\n  https://your-domain.atlassian.net/rest/api/3/myself\n```\n\n### **\"No tools loaded\"**\n\n```bash\n# Check available tools\nmcp-jira --list-tools\n\n# Load all tools (default)\nmcp-jira\n```\n\n---\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run tests (`npm test`)\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n---\n\n## 📄 License\n\nThis project is licensed under the ISC License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 🔗 Links\n\n- **NPM Package:** https://www.npmjs.com/package/@devpuccino/mcp-jira\n- **Repository:** https://bitbucket.org/devpuccino/mcp-jira\n- **MCP Documentation:** https://modelcontextprotocol.io\n- **Jira API Docs:** https://developer.atlassian.com/cloud/jira/platform/rest/v3/\n\n---\n\n## 🌟 Show Your Support\n\nIf you find this MCP server helpful, please:\n\n- ⭐ Star the repository on Bitbucket\n- 📦 Install from NPM to show download stats\n- 🐛 Report bugs and suggest features\n- 📝 Share with your team!\n\n---\n\n**Built with ❤️ by DevPuccino** | **MCP Standard Compliant (100%)**\n","readmeFilename":"README.md","_rev":"1-f54fd5d511e918c2be8feb383af0495e"}