mirrors/mcphub
1
0
Fork 0
mirror of https://github.com/samanhappy/mcphub.git synced 2025-12-24 02:39:19 -05:00
Code Issues Packages Projects Releases Wiki Activity

Add comprehensive Atlassian/Jira MCP server configuration examples and documentation

Browse Source 
Co-authored-by: samanhappy <2755122+samanhappy@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
2025-10-31 14:43:51 +00:00
parent 420214259c
commit ccd8ff50aa
5 changed files with 528 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
docs/configuration/mcp-settings.mdx
View File

@@ -207,6 +207,55 @@ MCPHub uses several configuration files:
}
```
### Productivity and Project Management
#### Atlassian (Jira & Confluence) Server
```json
{
"atlassian": {
"command": "uvx",
"args": [
"mcp-atlassian",
"--jira-url=${JIRA_URL}",
"--jira-username=${JIRA_USERNAME}",
"--jira-token=${JIRA_TOKEN}",
"--confluence-url=${CONFLUENCE_URL}",
"--confluence-username=${CONFLUENCE_USERNAME}",
"--confluence-token=${CONFLUENCE_TOKEN}"
],
"env": {}
}
}
```
**Jira Cloud Only Configuration:**
```json
{
"jira": {
"command": "uvx",
"args": [
"mcp-atlassian",
"--jira-url=${JIRA_URL}",
"--jira-username=${JIRA_USERNAME}",
"--jira-token=${JIRA_TOKEN}"
],
"env": {}
}
}
```
**Required Environment Variables:**
- `JIRA_URL`: Your Jira Cloud URL (e.g., `https://your-company.atlassian.net`)
- `JIRA_USERNAME`: Your Atlassian account email
- `JIRA_TOKEN`: API token from [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
- `CONFLUENCE_URL`: Your Confluence URL (e.g., `https://your-company.atlassian.net/wiki`)
- `CONFLUENCE_USERNAME`: Your Confluence account email (often same as Jira)
- `CONFLUENCE_TOKEN`: Confluence API token (can be same as Jira token for Cloud)
**Setup Guide:** See [examples/README_ATLASSIAN_JIRA.md](../../examples/README_ATLASSIAN_JIRA.md) for detailed setup instructions.
### Map and Location Services
#### Amap (高德地图) Server

18
examples/.env.atlassian.example Normal file
View File

@@ -0,0 +1,18 @@
# Atlassian Jira Cloud Configuration Example
# Copy this to your .env file and fill in your actual values
# Jira Configuration (Required)
JIRA_URL=https://your-company.atlassian.net
JIRA_USERNAME=your.email@company.com
JIRA_TOKEN=your_jira_api_token_here
# Confluence Configuration (Optional - only if you want to use Confluence)
CONFLUENCE_URL=https://your-company.atlassian.net/wiki
CONFLUENCE_USERNAME=your.email@company.com
CONFLUENCE_TOKEN=your_confluence_api_token_here
# Notes:
# 1. Get your API token from: https://id.atlassian.com/manage-profile/security/api-tokens
# 2. For Atlassian Cloud, you can often use the same API token for both Jira and Confluence
# 3. The username should be your Atlassian account email address
# 4. Never commit your .env file to version control

131
examples/QUICK_START_JIRA.md Normal file
View File

@@ -0,0 +1,131 @@
# Quick Start: Jira Cloud Integration
This is a quick 5-minute setup guide for connecting MCPHub to Jira Cloud.
## ⚡ Quick Setup (5 minutes)
### Step 1: Get Your Jira API Token (2 minutes)
1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click **"Create API token"**
3. Label it "MCPHub Integration"
4. **Copy the token** (you can't see it again!)
### Step 2: Find Your Jira URL (30 seconds)
Your Jira URL is what you see in your browser:
- Example: `https://mycompany.atlassian.net`
- ✅ Include: `https://` protocol
- ❌ Don't include: trailing `/` or `/jira`
### Step 3: Create .env File (1 minute)
Create a `.env` file in your MCPHub root directory:
```bash
JIRA_URL=https://mycompany.atlassian.net
JIRA_USERNAME=myemail@company.com
JIRA_TOKEN=paste_your_token_here
```
Replace with your actual values!
### Step 4: Update mcp_settings.json (1 minute)
Add this to your `mcp_settings.json`:
```json
{
"mcpServers": {
"jira": {
"command": "uvx",
"args": [
"mcp-atlassian",
"--jira-url=${JIRA_URL}",
"--jira-username=${JIRA_USERNAME}",
"--jira-token=${JIRA_TOKEN}"
]
}
}
}
```
### Step 5: Install UV & Start MCPHub (1 minute)
#### Install UV (if not already installed):
**macOS/Linux:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
**Windows:**
```powershell
irm https://astral.sh/uv/install.ps1 | iex
```
#### Start MCPHub:
**With Docker:**
```bash
docker run -p 3000:3000 \
--env-file .env \
-v ./mcp_settings.json:/app/mcp_settings.json \
samanhappy/mcphub
```
**Without Docker:**
```bash
pnpm install
pnpm dev
```
### Step 6: Verify Connection (30 seconds)
1. Open http://localhost:3000
2. Login: `admin` / `admin123`
3. Check dashboard - you should see "jira" server as "Connected" ✅
## 🎉 That's It!
You can now use Jira through MCPHub at:
- All servers: `http://localhost:3000/mcp`
- Jira only: `http://localhost:3000/mcp/jira`
## 🐛 Common Issues
### "uvx command not found"
```bash
# Install UV first (see Step 5)
curl -LsSf https://astral.sh/uv/install.sh | sh
```
### "401 Unauthorized"
- Double-check your API token
- Make sure username is your email
- Try regenerating the API token
### Server shows "Disconnected"
- Check logs for specific errors
- Verify .env file is in the correct location
- Ensure no trailing slashes in JIRA_URL
### "Downloading cryptography" errors
- This is usually temporary
- Wait and restart MCPHub
- Check internet connection
## 📚 Need More Help?
See [README_ATLASSIAN_JIRA.md](./README_ATLASSIAN_JIRA.md) for the complete guide with:
- Both Jira + Confluence setup
- Detailed troubleshooting
- Security best practices
- Example use cases
## 🔒 Security Reminder
- ✅ Never commit `.env` to git
- ✅ Keep API tokens secret
- ✅ Rotate tokens regularly
- ✅ Use different tokens for dev/prod

309
examples/README_ATLASSIAN_JIRA.md Normal file
View File

@@ -0,0 +1,309 @@
# Atlassian Jira Cloud MCP Server Configuration
This guide provides detailed instructions for configuring the MCP Atlassian server to connect to Jira Cloud in MCPHub.
## Prerequisites
1. **Jira Cloud Account**: You need access to a Jira Cloud instance
2. **API Token**: Generate an API token from your Atlassian account
3. **Python/UV**: The mcp-atlassian server requires Python and `uvx` (UV package manager)
## Step 1: Generate Jira API Token
1. Go to [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Click **"Create API token"**
3. Give it a label (e.g., "MCPHub Integration")
4. Copy the generated token (you won't be able to see it again!)
5. Save it securely
## Step 2: Get Your Jira Information
You'll need the following information:
- **JIRA_URL**: Your Jira Cloud URL (e.g., `https://your-company.atlassian.net`)
- **JIRA_USERNAME**: Your Atlassian account email (e.g., `your.email@company.com`)
- **JIRA_TOKEN**: The API token you generated in Step 1
## Step 3: Set Environment Variables
Create or update your `.env` file in the MCPHub root directory:
```bash
# Jira Configuration
JIRA_URL=https://your-company.atlassian.net
JIRA_USERNAME=your.email@company.com
JIRA_TOKEN=your_api_token_here
```
**Important Security Note**: Never commit your `.env` file to version control. It should be listed in `.gitignore`.
## Step 4: Configure MCPHub
### Option 1: Using Environment Variables (Recommended)
Update your `mcp_settings.json`:
```json
{
"mcpServers": {
"atlassian": {
"command": "uvx",
"args": [
"mcp-atlassian",
"--jira-url=${JIRA_URL}",
"--jira-username=${JIRA_USERNAME}",
"--jira-token=${JIRA_TOKEN}"
],
"env": {}
}
}
}
```
### Option 2: Direct Configuration (Not Recommended)
If you prefer not to use environment variables (less secure):
```json
{
"mcpServers": {
"atlassian": {
"command": "uvx",
"args": [
"mcp-atlassian",
"--jira-url=https://your-company.atlassian.net",
"--jira-username=your.email@company.com",
"--jira-token=your_api_token_here"
],
"env": {}
}
}
}
```
### Option 3: Jira Only (Without Confluence)
If you only want to use Jira and not Confluence:
```json
{
"mcpServers": {
"jira": {
"command": "uvx",
"args": [
"mcp-atlassian",
"--jira-url=${JIRA_URL}",
"--jira-username=${JIRA_USERNAME}",
"--jira-token=${JIRA_TOKEN}"
],
"env": {}
}
}
}
```
### Option 4: Both Jira and Confluence
To use both Jira and Confluence, you'll need API tokens for both:
```bash
# .env file
JIRA_URL=https://your-company.atlassian.net
JIRA_USERNAME=your.email@company.com
JIRA_TOKEN=your_jira_api_token
CONFLUENCE_URL=https://your-company.atlassian.net/wiki
CONFLUENCE_USERNAME=your.email@company.com
CONFLUENCE_TOKEN=your_confluence_api_token
```
```json
{
"mcpServers": {
"atlassian": {
"command": "uvx",
"args": [
"mcp-atlassian",
"--confluence-url=${CONFLUENCE_URL}",
"--confluence-username=${CONFLUENCE_USERNAME}",
"--confluence-token=${CONFLUENCE_TOKEN}",
"--jira-url=${JIRA_URL}",
"--jira-username=${JIRA_USERNAME}",
"--jira-token=${JIRA_TOKEN}"
],
"env": {}
}
}
}
```
**Note**: For Atlassian Cloud, you can often use the same API token for both Jira and Confluence.
## Step 5: Install UV (if not already installed)
The mcp-atlassian server uses `uvx` to run. Install UV if you haven't already:
### On macOS/Linux:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
### On Windows:
```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```
### Using pip:
```bash
pip install uv
```
## Step 6: Start MCPHub
### Using Docker:
```bash
docker run -p 3000:3000 \
-v ./mcp_settings.json:/app/mcp_settings.json \
-v ./data:/app/data \
-e JIRA_URL="${JIRA_URL}" \
-e JIRA_USERNAME="${JIRA_USERNAME}" \
-e JIRA_TOKEN="${JIRA_TOKEN}" \
samanhappy/mcphub
```
### Using Development Mode:
```bash
pnpm install
pnpm dev
```
### Using Production Mode:
```bash
pnpm install
pnpm build
pnpm start
```
## Verification
After starting MCPHub:
1. Open `http://localhost:3000` in your browser
2. Log in with default credentials: `admin` / `admin123`
3. Check the dashboard to see if the Atlassian server is connected
4. Look for the server status - it should show as "Connected" or "Running"
5. Check the logs for any connection errors
## Troubleshooting
### Error: "uvx command not found"
**Solution**: Install UV as described in Step 5 above.
### Error: "Traceback (most recent call last): File ... mcp-atlassian"
This error usually indicates:
1. Missing or incorrect API credentials
2. Network connectivity issues
3. Python dependency issues
**Solutions**:
- Verify your API token is correct
- Ensure your Jira URL doesn't have trailing slashes
- Check that your username is the email address you use for Atlassian
- Verify network connectivity to your Jira instance
- Try regenerating your API token
### Error: "401 Unauthorized"
**Solution**:
- Double-check your API token is correct
- Ensure you're using the email address associated with your Atlassian account
- Regenerate your API token if needed
### Error: "403 Forbidden"
**Solution**:
- Check that your account has appropriate permissions in Jira
- Verify your Jira administrator hasn't restricted API access
### Error: Downloading cryptography errors
**Solution**:
- This is usually a transient network or Python package installation issue
- Wait a moment and try restarting MCPHub
- Ensure you have a stable internet connection
- If the issue persists, try installing mcp-atlassian manually:
```bash
uvx mcp-atlassian --help
```
### Server shows as "Disconnected"
**Solution**:
1. Check MCPHub logs for specific error messages
2. Verify all environment variables are set correctly
3. Test the connection manually:
```bash
uvx mcp-atlassian \
--jira-url=https://your-company.atlassian.net \
--jira-username=your.email@company.com \
--jira-token=your_token
```
## Using the Jira MCP Server
Once connected, you can use the Jira MCP server to:
- **Search Issues**: Query Jira issues using JQL
- **Read Issues**: Get detailed information about specific issues
- **Access Projects**: List and retrieve project metadata
- **View Comments**: Read issue comments and discussions
- **Get Transitions**: Check available status transitions for issues
Access the server through:
- **All servers**: `http://localhost:3000/mcp`
- **Specific server**: `http://localhost:3000/mcp/atlassian`
- **Server groups**: `http://localhost:3000/mcp/{group}` (if configured)
## Additional Resources
- [MCP Atlassian GitHub Repository](https://github.com/sooperset/mcp-atlassian)
- [Atlassian API Token Documentation](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/)
- [Jira Cloud REST API](https://developer.atlassian.com/cloud/jira/platform/rest/v3/)
- [MCPHub Documentation](https://docs.mcphubx.com/)
## Security Best Practices
1. ✅ **Always use environment variables** for sensitive credentials
2. ✅ **Never commit `.env` files** to version control
3. ✅ **Rotate API tokens** regularly
4. ✅ **Use separate tokens** for different environments (dev, staging, prod)
5. ✅ **Restrict API token permissions** to only what's needed
6. ✅ **Monitor token usage** in Atlassian account settings
7. ✅ **Revoke unused tokens** immediately
## Example Use Cases
### Example 1: Search for Issues
Query: "List all open bugs assigned to me"
- Tool: `jira_search_issues`
- JQL: `project = MYPROJECT AND status = Open AND assignee = currentUser() AND type = Bug`
### Example 2: Get Issue Details
Query: "Show me details of issue PROJ-123"
- Tool: `jira_get_issue`
- Issue Key: `PROJ-123`
### Example 3: List Projects
Query: "What Jira projects do I have access to?"
- Tool: `jira_list_projects`
## Need Help?
If you're still experiencing issues:
1. Check the [MCPHub Discord community](https://discord.gg/qMKNsn5Q)
2. Review [MCPHub GitHub Issues](https://github.com/samanhappy/mcphub/issues)
3. Check [mcp-atlassian Issues](https://github.com/sooperset/mcp-atlassian/issues)
4. Contact your Jira administrator for API access questions

21
examples/mcp_settings_atlassian_jira.json Normal file
View File

@@ -0,0 +1,21 @@
{
"mcpServers": {
"atlassian": {
"command": "uvx",
"args": [
"mcp-atlassian",
"--jira-url=${JIRA_URL}",
"--jira-username=${JIRA_USERNAME}",
"--jira-token=${JIRA_TOKEN}"
],
"env": {}
}
},
"users": [
{
"username": "admin",
"password": "$2b$10$Vt7krIvjNgyN67LXqly0uOcTpN0LI55cYRbcKC71pUDAP0nJ7RPa.",
"isAdmin": true
}
]
}