# Jira MCP Server
A clean, reliable [Model Context Protocol](https://modelcontextprotocol.io) server for Jira integration, designed for use with Claude Desktop and other MCP clients.
## Why This Exists
The existing Jira MCP servers have quality issues:
- Pydantic dependency conflicts
- Deprecated API usage (v2 instead of v3)
- Poor error handling
- Unreliable connections
This implementation focuses on:
- ✅ Modern Jira REST API v3
- ✅ Minimal, stable dependencies
- ✅ Proper error handling
- ✅ Multi-instance support
- ✅ Type safety throughout
## Features
### Core Operations
- 🔍 **Search issues** with JQL (Jira Query Language)
- 📄 **Get issue details** with full field information
- ➕ **Create issues** with descriptions, labels, and custom fields
- ✏️ **Update issues** (summary, description, labels, etc.)
- 💬 **Add comments** to issues
- 🔄 **Transition issues** between statuses
- 📋 **List projects** accessible to the user
### Multi-Instance Support
Connect to multiple Jira instances simultaneously:
- Different organizations
- Personal and work accounts
- Multiple teams
## Quick Start
### 1. Installation
**Option A: Install from PyPI (Recommended)**
```bash
pip install jira-mcp-server
```
**Option B: Install from source**
```bash
git clone https://github.com/Positronic-AI/jira-mcp.git
cd jira-mcp
pip install -e .
```
### 2. Get Your Jira API Token
1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Give it a name (e.g., "Claude Desktop MCP")
4. Copy the token
### 3. Test Connection
```bash
export JIRA_MYCOMPANY_URL="https://your-company.atlassian.net"
export JIRA_MYCOMPANY_EMAIL="your.email@company.com"
export JIRA_MYCOMPANY_TOKEN="your_api_token_here"
jira-mcp --test-connection mycompany
```
You should see:
```
✓ Connected successfully!
User: Your Name (your@email.com)
Account ID: 123abc...
Accessible projects: N
```
### 4. Configure Claude Desktop
Edit your Claude Desktop config file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
Add this configuration:
```json
{
"mcpServers": {
"jira": {
"command": "jira-mcp",
"args": ["--instance", "mycompany"],
"env": {
"JIRA_MYCOMPANY_URL": "https://your-company.atlassian.net",
"JIRA_MYCOMPANY_EMAIL": "your.email@company.com",
"JIRA_MYCOMPANY_TOKEN": "your_api_token_here"
}
}
}
}
```
**Note**: If you installed in a virtual environment, use the full path to `jira-mcp`, e.g., `/path/to/venv/bin/jira-mcp`
### 5. Restart Claude Desktop
Completely quit and reopen Claude Desktop.
### 6. Test It!
Try these commands in Claude:
```
List my Jira projects
Search for issues assigned to me
Show me PROJECT-123
Create a new task in PROJECT called "Test MCP integration"
```
## Usage Examples
### Natural Language Commands
Once configured, you can use natural language with Claude:
- "Find all open bugs in the MOBILE project"
- "Show me high priority issues assigned to me"
- "Create a task about fixing the login page"
- "Add a comment to PROJ-42 saying the fix is deployed"
- "Move PROJ-42 to In Progress"
- "Update the summary of PROJ-42 to include more details"
### Direct JQL Queries
```
Search Jira with: project = PROJ AND status = "In Progress" ORDER BY priority DESC
```
## Multi-Instance Configuration
To connect multiple Jira instances:
```json
{
"mcpServers": {
"jira-work": {
"command": "jira-mcp",
"args": ["--instance", "work"],
"env": {
"JIRA_WORK_URL": "https://company.atlassian.net",
"JIRA_WORK_EMAIL": "you@company.com",
"JIRA_WORK_TOKEN": "token1"
}
},
"jira-personal": {
"command": "jira-mcp",
"args": ["--instance", "personal"],
"env": {
"JIRA_PERSONAL_URL": "https://personal.atlassian.net",
"JIRA_PERSONAL_EMAIL": "you@personal.com",
"JIRA_PERSONAL_TOKEN": "token2"
}
}
}
}
```
Claude will know which instance to use based on context.
## Architecture
```
jira-mcp/
├── server.py # Main MCP server
├── jira_client.py # Jira REST API v3 wrapper
├── config.py # Configuration management
├── requirements.txt # Python dependencies
└── examples/ # Configuration examples
```
### Key Design Decisions
**Minimal Dependencies**: Only essential, stable packages (mcp, httpx, pydantic, python-dotenv)
**Modern API**: Uses Jira REST API v3 (`/rest/api/3/search/jql`) instead of deprecated v2
**Type Safety**: Full type hints throughout for better IDE support and fewer bugs
**Error Handling**: Clear error messages propagated from Jira API
**Multi-Instance**: Environment-based configuration for multiple Jira instances
## Available Tools
The server exposes these MCP tools:
| Tool | Description |
|------|-------------|
| `jira_search` | Search issues using JQL with pagination |
| `jira_get_issue` | Get detailed issue information |
| `jira_create_issue` | Create new issues with custom fields |
| `jira_update_issue` | Update existing issue fields |
| `jira_add_comment` | Add comments to issues |
| `jira_transition_issue` | Change issue status |
| `jira_list_projects` | List accessible projects |
## Troubleshooting
### Connection fails
- Verify your API token is correct
- Check the Jira URL has no trailing slash
- Ensure your email matches the Atlassian account
- Test with: `jira-mcp --test-connection <instance>`
### Claude Desktop doesn't see the server
- Verify JSON config is valid
- Use absolute paths (not `~/` or relative)
- Restart Claude Desktop completely
- Check Claude Desktop logs for errors
### "Module not found" errors
- Ensure `jira-mcp-server` is installed: `pip install jira-mcp-server`
- If using a virtual environment, ensure it's activated or use the full path
### "Field cannot be set" errors
- Not all fields are available on all projects
- Check your project's issue type screen configuration
- Common issue: `priority` field not on screen (make it optional)
## Contributing
Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
Areas we'd especially appreciate help:
- Unit and integration tests
- Jira Data Center support
- Attachment handling
- Sprint/board operations
- Custom field improvements
## Development
```bash
# Clone and setup
git clone https://github.com/Positronic-AI/jira-mcp.git
cd jira-mcp
pip install -e ".[dev]"
# Test connection
export JIRA_TEST_URL="https://test.atlassian.net"
export JIRA_TEST_EMAIL="test@example.com"
export JIRA_TEST_TOKEN="test_token"
jira-mcp --test-connection test
```
## License
MIT License - see [LICENSE](LICENSE) for details.
## Acknowledgments
- Built for use with [Claude Desktop](https://claude.ai/desktop)
- Uses the [Model Context Protocol](https://modelcontextprotocol.io)
- Inspired by the need for reliable Jira automation
## Support
- 🐛 [Report bugs](https://github.com/yourusername/jira-mcp/issues)
- 💡 [Request features](https://github.com/yourusername/jira-mcp/issues)
- 📖 [Documentation](https://github.com/yourusername/jira-mcp/wiki)
- 💬 [Discussions](https://github.com/yourusername/jira-mcp/discussions)
---
**Note**: This is an independent project and is not affiliated with Atlassian or Anthropic.
Raw data
{
"_id": null,
"home_page": null,
"name": "jira-mcp-simple",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Ben Vierck <ben@positronic.ai>",
"keywords": "jira, mcp, model-context-protocol, claude, anthropic, api, atlassian",
"author": null,
"author_email": "Ben Vierck <ben@positronic.ai>",
"download_url": "https://files.pythonhosted.org/packages/2d/2f/653df5f57dccc8b789cf1f75d0fedb938b6ac0284d1944bf8ec3865f8e93/jira_mcp_simple-1.0.0.tar.gz",
"platform": null,
"description": "# Jira MCP Server\n\nA clean, reliable [Model Context Protocol](https://modelcontextprotocol.io) server for Jira integration, designed for use with Claude Desktop and other MCP clients.\n\n## Why This Exists\n\nThe existing Jira MCP servers have quality issues:\n- Pydantic dependency conflicts\n- Deprecated API usage (v2 instead of v3)\n- Poor error handling\n- Unreliable connections\n\nThis implementation focuses on:\n- \u2705 Modern Jira REST API v3\n- \u2705 Minimal, stable dependencies\n- \u2705 Proper error handling\n- \u2705 Multi-instance support\n- \u2705 Type safety throughout\n\n## Features\n\n### Core Operations\n- \ud83d\udd0d **Search issues** with JQL (Jira Query Language)\n- \ud83d\udcc4 **Get issue details** with full field information\n- \u2795 **Create issues** with descriptions, labels, and custom fields\n- \u270f\ufe0f **Update issues** (summary, description, labels, etc.)\n- \ud83d\udcac **Add comments** to issues\n- \ud83d\udd04 **Transition issues** between statuses\n- \ud83d\udccb **List projects** accessible to the user\n\n### Multi-Instance Support\nConnect to multiple Jira instances simultaneously:\n- Different organizations\n- Personal and work accounts\n- Multiple teams\n\n## Quick Start\n\n### 1. Installation\n\n**Option A: Install from PyPI (Recommended)**\n\n```bash\npip install jira-mcp-server\n```\n\n**Option B: Install from source**\n\n```bash\ngit clone https://github.com/Positronic-AI/jira-mcp.git\ncd jira-mcp\npip install -e .\n```\n\n### 2. Get 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 name (e.g., \"Claude Desktop MCP\")\n4. Copy the token\n\n### 3. Test Connection\n\n```bash\nexport JIRA_MYCOMPANY_URL=\"https://your-company.atlassian.net\"\nexport JIRA_MYCOMPANY_EMAIL=\"your.email@company.com\"\nexport JIRA_MYCOMPANY_TOKEN=\"your_api_token_here\"\n\njira-mcp --test-connection mycompany\n```\n\nYou should see:\n```\n\u2713 Connected successfully!\n User: Your Name (your@email.com)\n Account ID: 123abc...\n Accessible projects: N\n```\n\n### 4. Configure Claude Desktop\n\nEdit your Claude Desktop config file:\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\nAdd this configuration:\n\n```json\n{\n \"mcpServers\": {\n \"jira\": {\n \"command\": \"jira-mcp\",\n \"args\": [\"--instance\", \"mycompany\"],\n \"env\": {\n \"JIRA_MYCOMPANY_URL\": \"https://your-company.atlassian.net\",\n \"JIRA_MYCOMPANY_EMAIL\": \"your.email@company.com\",\n \"JIRA_MYCOMPANY_TOKEN\": \"your_api_token_here\"\n }\n }\n }\n}\n```\n\n**Note**: If you installed in a virtual environment, use the full path to `jira-mcp`, e.g., `/path/to/venv/bin/jira-mcp`\n\n### 5. Restart Claude Desktop\n\nCompletely quit and reopen Claude Desktop.\n\n### 6. Test It!\n\nTry these commands in Claude:\n\n```\nList my Jira projects\n\nSearch for issues assigned to me\n\nShow me PROJECT-123\n\nCreate a new task in PROJECT called \"Test MCP integration\"\n```\n\n## Usage Examples\n\n### Natural Language Commands\n\nOnce configured, you can use natural language with Claude:\n\n- \"Find all open bugs in the MOBILE project\"\n- \"Show me high priority issues assigned to me\"\n- \"Create a task about fixing the login page\"\n- \"Add a comment to PROJ-42 saying the fix is deployed\"\n- \"Move PROJ-42 to In Progress\"\n- \"Update the summary of PROJ-42 to include more details\"\n\n### Direct JQL Queries\n\n```\nSearch Jira with: project = PROJ AND status = \"In Progress\" ORDER BY priority DESC\n```\n\n## Multi-Instance Configuration\n\nTo connect multiple Jira instances:\n\n```json\n{\n \"mcpServers\": {\n \"jira-work\": {\n \"command\": \"jira-mcp\",\n \"args\": [\"--instance\", \"work\"],\n \"env\": {\n \"JIRA_WORK_URL\": \"https://company.atlassian.net\",\n \"JIRA_WORK_EMAIL\": \"you@company.com\",\n \"JIRA_WORK_TOKEN\": \"token1\"\n }\n },\n \"jira-personal\": {\n \"command\": \"jira-mcp\",\n \"args\": [\"--instance\", \"personal\"],\n \"env\": {\n \"JIRA_PERSONAL_URL\": \"https://personal.atlassian.net\",\n \"JIRA_PERSONAL_EMAIL\": \"you@personal.com\",\n \"JIRA_PERSONAL_TOKEN\": \"token2\"\n }\n }\n }\n}\n```\n\nClaude will know which instance to use based on context.\n\n## Architecture\n\n```\njira-mcp/\n\u251c\u2500\u2500 server.py # Main MCP server\n\u251c\u2500\u2500 jira_client.py # Jira REST API v3 wrapper\n\u251c\u2500\u2500 config.py # Configuration management\n\u251c\u2500\u2500 requirements.txt # Python dependencies\n\u2514\u2500\u2500 examples/ # Configuration examples\n```\n\n### Key Design Decisions\n\n**Minimal Dependencies**: Only essential, stable packages (mcp, httpx, pydantic, python-dotenv)\n\n**Modern API**: Uses Jira REST API v3 (`/rest/api/3/search/jql`) instead of deprecated v2\n\n**Type Safety**: Full type hints throughout for better IDE support and fewer bugs\n\n**Error Handling**: Clear error messages propagated from Jira API\n\n**Multi-Instance**: Environment-based configuration for multiple Jira instances\n\n## Available Tools\n\nThe server exposes these MCP tools:\n\n| Tool | Description |\n|------|-------------|\n| `jira_search` | Search issues using JQL with pagination |\n| `jira_get_issue` | Get detailed issue information |\n| `jira_create_issue` | Create new issues with custom fields |\n| `jira_update_issue` | Update existing issue fields |\n| `jira_add_comment` | Add comments to issues |\n| `jira_transition_issue` | Change issue status |\n| `jira_list_projects` | List accessible projects |\n\n## Troubleshooting\n\n### Connection fails\n\n- Verify your API token is correct\n- Check the Jira URL has no trailing slash\n- Ensure your email matches the Atlassian account\n- Test with: `jira-mcp --test-connection <instance>`\n\n### Claude Desktop doesn't see the server\n\n- Verify JSON config is valid\n- Use absolute paths (not `~/` or relative)\n- Restart Claude Desktop completely\n- Check Claude Desktop logs for errors\n\n### \"Module not found\" errors\n\n- Ensure `jira-mcp-server` is installed: `pip install jira-mcp-server`\n- If using a virtual environment, ensure it's activated or use the full path\n\n### \"Field cannot be set\" errors\n\n- Not all fields are available on all projects\n- Check your project's issue type screen configuration\n- Common issue: `priority` field not on screen (make it optional)\n\n## Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\nAreas we'd especially appreciate help:\n- Unit and integration tests\n- Jira Data Center support\n- Attachment handling\n- Sprint/board operations\n- Custom field improvements\n\n## Development\n\n```bash\n# Clone and setup\ngit clone https://github.com/Positronic-AI/jira-mcp.git\ncd jira-mcp\npip install -e \".[dev]\"\n\n# Test connection\nexport JIRA_TEST_URL=\"https://test.atlassian.net\"\nexport JIRA_TEST_EMAIL=\"test@example.com\"\nexport JIRA_TEST_TOKEN=\"test_token\"\njira-mcp --test-connection test\n```\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Acknowledgments\n\n- Built for use with [Claude Desktop](https://claude.ai/desktop)\n- Uses the [Model Context Protocol](https://modelcontextprotocol.io)\n- Inspired by the need for reliable Jira automation\n\n## Support\n\n- \ud83d\udc1b [Report bugs](https://github.com/yourusername/jira-mcp/issues)\n- \ud83d\udca1 [Request features](https://github.com/yourusername/jira-mcp/issues)\n- \ud83d\udcd6 [Documentation](https://github.com/yourusername/jira-mcp/wiki)\n- \ud83d\udcac [Discussions](https://github.com/yourusername/jira-mcp/discussions)\n\n---\n\n**Note**: This is an independent project and is not affiliated with Atlassian or Anthropic.\n",
"bugtrack_url": null,
"license": null,
"summary": "A clean, reliable MCP server for Jira integration with Claude Desktop",
"version": "1.0.0",
"project_urls": {
"Changelog": "https://github.com/Positronic-AI/jira-mcp/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/Positronic-AI/jira-mcp#readme",
"Homepage": "https://github.com/Positronic-AI/jira-mcp",
"Issues": "https://github.com/Positronic-AI/jira-mcp/issues",
"Repository": "https://github.com/Positronic-AI/jira-mcp"
},
"split_keywords": [
"jira",
" mcp",
" model-context-protocol",
" claude",
" anthropic",
" api",
" atlassian"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "eb7c1c57ff4702d1733fa6b54a55e4f3e018832397df0046bc1c2e16463cca18",
"md5": "e0f12e72fd3c1575c14b4fa25d921dff",
"sha256": "b017078858a5b3c64dd3db0fedf106b960593bbf8276847d2aea259ab9208ccd"
},
"downloads": -1,
"filename": "jira_mcp_simple-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e0f12e72fd3c1575c14b4fa25d921dff",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 14446,
"upload_time": "2025-10-28T16:41:21",
"upload_time_iso_8601": "2025-10-28T16:41:21.357938Z",
"url": "https://files.pythonhosted.org/packages/eb/7c/1c57ff4702d1733fa6b54a55e4f3e018832397df0046bc1c2e16463cca18/jira_mcp_simple-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2d2f653df5f57dccc8b789cf1f75d0fedb938b6ac0284d1944bf8ec3865f8e93",
"md5": "429ae46fa0051ed04757df48bcbcc8ff",
"sha256": "af6445d5b467cf0c222018d99a0c01e4bd00d27d3ebd006eb0996f35bdff51b3"
},
"downloads": -1,
"filename": "jira_mcp_simple-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "429ae46fa0051ed04757df48bcbcc8ff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 18258,
"upload_time": "2025-10-28T16:41:22",
"upload_time_iso_8601": "2025-10-28T16:41:22.335496Z",
"url": "https://files.pythonhosted.org/packages/2d/2f/653df5f57dccc8b789cf1f75d0fedb938b6ac0284d1944bf8ec3865f8e93/jira_mcp_simple-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-28 16:41:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Positronic-AI",
"github_project": "jira-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "mcp",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "httpx",
"specs": [
[
">=",
"0.27.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
],
[
"<",
"3.0.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.0.0"
]
]
}
],
"lcname": "jira-mcp-simple"
}
JSON
