# JIRA MCP Server
A Model Context Protocol (MCP) server for JIRA integration that allows AI assistants to read user stories and issues from JIRA projects.
## 🚀 Quick Start with Docker
```bash
# Pull from Docker Hub
docker pull yourusername/jira-mcp-server:latest
# Run with environment variables
docker run -d \
-e JIRA_URL=https://your-company.atlassian.net \
-e JIRA_USERNAME=your-email@company.com \
-e JIRA_API_TOKEN=your-api-token \
--name jira-mcp-server \
yourusername/jira-mcp-server:latest
```
## 📋 Features
- **Get User Stories**: Fetch user stories from JIRA projects
- **Get Issues**: Retrieve specific JIRA issues by key
- **MCP Protocol**: Standard Model Context Protocol for AI integration
- **Docker Ready**: Pre-built Docker images available
- **Secure**: Uses JIRA API tokens for authentication
## 🔧 Configuration
### Required Environment Variables
| Variable | Description | Example |
|----------|-------------|---------|
| `JIRA_URL` | Your JIRA instance URL | `https://company.atlassian.net` |
| `JIRA_USERNAME` | Your JIRA email | `user@company.com` |
| `JIRA_API_TOKEN` | JIRA API token | `ATATT3xFfGF0...` |
### Getting JIRA API Token
1. Go to [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Click "Create API token"
3. Copy the generated token
## 🐳 Docker Usage
### Using Docker Hub Image
```bash
# Basic usage
docker run -d \
-e JIRA_URL=https://your-company.atlassian.net \
-e JIRA_USERNAME=your-email@company.com \
-e JIRA_API_TOKEN=your-api-token \
yourusername/jira-mcp-server:latest
# With custom name and restart policy
docker run -d \
--name jira-mcp \
--restart unless-stopped \
-e JIRA_URL=https://your-company.atlassian.net \
-e JIRA_USERNAME=your-email@company.com \
-e JIRA_API_TOKEN=your-api-token \
yourusername/jira-mcp-server:latest
```
### Using Docker Compose
```yaml
version: '3.8'
services:
jira-mcp-server:
image: yourusername/jira-mcp-server:latest
environment:
- JIRA_URL=https://your-company.atlassian.net
- JIRA_USERNAME=your-email@company.com
- JIRA_API_TOKEN=your-api-token
restart: unless-stopped
```
## 🛠️ Local Development
### Prerequisites
- Python 3.10+
- [uv](https://github.com/astral-sh/uv) package manager
### Setup
```bash
# Clone repository
git clone https://github.com/yourusername/jira-mcp-server.git
cd jira-mcp-server
# Install dependencies
uv sync
# Copy environment template
cp .env.example .env
# Edit .env with your JIRA credentials
nano .env
# Test connection
uv run python test_connection.py
# Run server
uv run python server.py
```
## 🔌 MCP Integration
### With Claude Desktop
Add to your Claude Desktop MCP configuration:
```json
{
"mcpServers": {
"jira": {
"command": "docker",
"args": [
"exec", "-i", "jira-mcp-server",
"uv", "run", "python", "server.py"
]
}
}
}
```
### With Other MCP Clients
The server communicates via stdio using the standard MCP protocol:
```bash
# Send MCP requests via stdin
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | docker exec -i jira-mcp-server uv run python server.py
```
## 📖 Available Tools
### `get_user_stories`
Fetch user stories from JIRA projects.
**Parameters:**
- `project` (optional): JIRA project key (e.g., "KW")
- `limit` (optional): Maximum number of stories (default: 10, max: 100)
**Example:**
```json
{
"name": "get_user_stories",
"arguments": {
"project": "KW",
"limit": 20
}
}
```
### `get_issue`
Get a specific JIRA issue by key.
**Parameters:**
- `key` (required): JIRA issue key (e.g., "KW-123")
**Example:**
```json
{
"name": "get_issue",
"arguments": {
"key": "KW-123"
}
}
```
## 🧪 Testing
```bash
# Run all tests
./run_tests.sh
# Unit tests only
uv run python -m pytest test_unit.py -v
# Integration test (requires JIRA access)
uv run python test_integration.py
# Test MCP protocol
uv run python test_mcp_client.py
```
## 🔒 Security
- Uses JIRA API tokens (not passwords)
- Validates input parameters
- Rate limiting and timeout protection
- No data persistence or logging of sensitive information
## 📝 License
MIT License - see [LICENSE](LICENSE) file for details.
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
## 📞 Support
- **Issues**: [GitHub Issues](https://github.com/yourusername/jira-mcp-server/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/jira-mcp-server/discussions)
## 🏷️ Tags
`mcp` `jira` `ai` `model-context-protocol` `docker` `python` `atlassian`
Raw data
{
"_id": null,
"home_page": null,
"name": "jira-mcp-standalone",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, atlassian, jira, mcp, model-context-protocol",
"author": null,
"author_email": "Your Name <your.email@example.com>",
"download_url": "https://files.pythonhosted.org/packages/c4/89/21ec5b17c1e1fea00ca370f15170483c5ee1259f34ac77d90198390985fd/jira_mcp_standalone-1.0.0.tar.gz",
"platform": null,
"description": "# JIRA MCP Server\n\nA Model Context Protocol (MCP) server for JIRA integration that allows AI assistants to read user stories and issues from JIRA projects.\n\n## \ud83d\ude80 Quick Start with Docker\n\n```bash\n# Pull from Docker Hub\ndocker pull yourusername/jira-mcp-server:latest\n\n# Run with environment variables\ndocker run -d \\\n -e JIRA_URL=https://your-company.atlassian.net \\\n -e JIRA_USERNAME=your-email@company.com \\\n -e JIRA_API_TOKEN=your-api-token \\\n --name jira-mcp-server \\\n yourusername/jira-mcp-server:latest\n```\n\n## \ud83d\udccb Features\n\n- **Get User Stories**: Fetch user stories from JIRA projects\n- **Get Issues**: Retrieve specific JIRA issues by key\n- **MCP Protocol**: Standard Model Context Protocol for AI integration\n- **Docker Ready**: Pre-built Docker images available\n- **Secure**: Uses JIRA API tokens for authentication\n\n## \ud83d\udd27 Configuration\n\n### Required Environment Variables\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| `JIRA_URL` | Your JIRA instance URL | `https://company.atlassian.net` |\n| `JIRA_USERNAME` | Your JIRA email | `user@company.com` |\n| `JIRA_API_TOKEN` | JIRA API token | `ATATT3xFfGF0...` |\n\n### Getting JIRA API Token\n\n1. Go to [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens)\n2. Click \"Create API token\"\n3. Copy the generated token\n\n## \ud83d\udc33 Docker Usage\n\n### Using Docker Hub Image\n\n```bash\n# Basic usage\ndocker run -d \\\n -e JIRA_URL=https://your-company.atlassian.net \\\n -e JIRA_USERNAME=your-email@company.com \\\n -e JIRA_API_TOKEN=your-api-token \\\n yourusername/jira-mcp-server:latest\n\n# With custom name and restart policy\ndocker run -d \\\n --name jira-mcp \\\n --restart unless-stopped \\\n -e JIRA_URL=https://your-company.atlassian.net \\\n -e JIRA_USERNAME=your-email@company.com \\\n -e JIRA_API_TOKEN=your-api-token \\\n yourusername/jira-mcp-server:latest\n```\n\n### Using Docker Compose\n\n```yaml\nversion: '3.8'\nservices:\n jira-mcp-server:\n image: yourusername/jira-mcp-server:latest\n environment:\n - JIRA_URL=https://your-company.atlassian.net\n - JIRA_USERNAME=your-email@company.com\n - JIRA_API_TOKEN=your-api-token\n restart: unless-stopped\n```\n\n## \ud83d\udee0\ufe0f Local Development\n\n### Prerequisites\n\n- Python 3.10+\n- [uv](https://github.com/astral-sh/uv) package manager\n\n### Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/yourusername/jira-mcp-server.git\ncd jira-mcp-server\n\n# Install dependencies\nuv sync\n\n# Copy environment template\ncp .env.example .env\n\n# Edit .env with your JIRA credentials\nnano .env\n\n# Test connection\nuv run python test_connection.py\n\n# Run server\nuv run python server.py\n```\n\n## \ud83d\udd0c MCP Integration\n\n### With Claude Desktop\n\nAdd to your Claude Desktop MCP configuration:\n\n```json\n{\n \"mcpServers\": {\n \"jira\": {\n \"command\": \"docker\",\n \"args\": [\n \"exec\", \"-i\", \"jira-mcp-server\",\n \"uv\", \"run\", \"python\", \"server.py\"\n ]\n }\n }\n}\n```\n\n### With Other MCP Clients\n\nThe server communicates via stdio using the standard MCP protocol:\n\n```bash\n# Send MCP requests via stdin\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}' | docker exec -i jira-mcp-server uv run python server.py\n```\n\n## \ud83d\udcd6 Available Tools\n\n### `get_user_stories`\n\nFetch user stories from JIRA projects.\n\n**Parameters:**\n- `project` (optional): JIRA project key (e.g., \"KW\")\n- `limit` (optional): Maximum number of stories (default: 10, max: 100)\n\n**Example:**\n```json\n{\n \"name\": \"get_user_stories\",\n \"arguments\": {\n \"project\": \"KW\",\n \"limit\": 20\n }\n}\n```\n\n### `get_issue`\n\nGet a specific JIRA issue by key.\n\n**Parameters:**\n- `key` (required): JIRA issue key (e.g., \"KW-123\")\n\n**Example:**\n```json\n{\n \"name\": \"get_issue\",\n \"arguments\": {\n \"key\": \"KW-123\"\n }\n}\n```\n\n## \ud83e\uddea Testing\n\n```bash\n# Run all tests\n./run_tests.sh\n\n# Unit tests only\nuv run python -m pytest test_unit.py -v\n\n# Integration test (requires JIRA access)\nuv run python test_integration.py\n\n# Test MCP protocol\nuv run python test_mcp_client.py\n```\n\n## \ud83d\udd12 Security\n\n- Uses JIRA API tokens (not passwords)\n- Validates input parameters\n- Rate limiting and timeout protection\n- No data persistence or logging of sensitive information\n\n## \ud83d\udcdd License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## \ud83e\udd1d Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n## \ud83d\udcde Support\n\n- **Issues**: [GitHub Issues](https://github.com/yourusername/jira-mcp-server/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/yourusername/jira-mcp-server/discussions)\n\n## \ud83c\udff7\ufe0f Tags\n\n`mcp` `jira` `ai` `model-context-protocol` `docker` `python` `atlassian`",
"bugtrack_url": null,
"license": "MIT",
"summary": "JIRA MCP Server for AI integration - fetch user stories and issues",
"version": "1.0.0",
"project_urls": {
"Documentation": "https://github.com/yourusername/jira-mcp-server#readme",
"Homepage": "https://github.com/yourusername/jira-mcp-server",
"Issues": "https://github.com/yourusername/jira-mcp-server/issues",
"Repository": "https://github.com/yourusername/jira-mcp-server.git"
},
"split_keywords": [
"ai",
" atlassian",
" jira",
" mcp",
" model-context-protocol"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b42a3199d104aed95088941a2aa7adc210ff7349fbfac017d0396f6446eecd86",
"md5": "ec7122f1fa6745aaefb7242eacfd660f",
"sha256": "858f74e1949750ee81c409939f3a3e4e37290d3791506fda80731b5c78dae829"
},
"downloads": -1,
"filename": "jira_mcp_standalone-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ec7122f1fa6745aaefb7242eacfd660f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 99323,
"upload_time": "2025-09-10T11:17:15",
"upload_time_iso_8601": "2025-09-10T11:17:15.509721Z",
"url": "https://files.pythonhosted.org/packages/b4/2a/3199d104aed95088941a2aa7adc210ff7349fbfac017d0396f6446eecd86/jira_mcp_standalone-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c48921ec5b17c1e1fea00ca370f15170483c5ee1259f34ac77d90198390985fd",
"md5": "8e63c0e5ecd57b1b40fb3082b80186ce",
"sha256": "90c4ec01c05adccb1890c0f43c6281dde16c33c04d9337c6a336c3fbac4421a3"
},
"downloads": -1,
"filename": "jira_mcp_standalone-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "8e63c0e5ecd57b1b40fb3082b80186ce",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 77973,
"upload_time": "2025-09-10T11:17:17",
"upload_time_iso_8601": "2025-09-10T11:17:17.207747Z",
"url": "https://files.pythonhosted.org/packages/c4/89/21ec5b17c1e1fea00ca370f15170483c5ee1259f34ac77d90198390985fd/jira_mcp_standalone-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-10 11:17:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "jira-mcp-server#readme",
"github_not_found": true,
"lcname": "jira-mcp-standalone"
}
JSON
