From ccd8ff50aaf6d13ed6f566580ac791899ffe8cc2 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 31 Oct 2025 14:43:51 +0000 Subject: [PATCH] Add comprehensive Atlassian/Jira MCP server configuration examples and documentation Co-authored-by: samanhappy <2755122+samanhappy@users.noreply.github.com> --- docs/configuration/mcp-settings.mdx | 49 ++++ examples/.env.atlassian.example | 18 ++ examples/QUICK_START_JIRA.md | 131 +++++++++ examples/README_ATLASSIAN_JIRA.md | 309 ++++++++++++++++++++++ examples/mcp_settings_atlassian_jira.json | 21 ++ 5 files changed, 528 insertions(+) create mode 100644 examples/.env.atlassian.example create mode 100644 examples/QUICK_START_JIRA.md create mode 100644 examples/README_ATLASSIAN_JIRA.md create mode 100644 examples/mcp_settings_atlassian_jira.json diff --git a/docs/configuration/mcp-settings.mdx b/docs/configuration/mcp-settings.mdx index 49cc9c6..79a0374 100644 --- a/docs/configuration/mcp-settings.mdx +++ b/docs/configuration/mcp-settings.mdx @@ -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 diff --git a/examples/.env.atlassian.example b/examples/.env.atlassian.example new file mode 100644 index 0000000..f2817cd --- /dev/null +++ b/examples/.env.atlassian.example @@ -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 diff --git a/examples/QUICK_START_JIRA.md b/examples/QUICK_START_JIRA.md new file mode 100644 index 0000000..e4dccb5 --- /dev/null +++ b/examples/QUICK_START_JIRA.md @@ -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 diff --git a/examples/README_ATLASSIAN_JIRA.md b/examples/README_ATLASSIAN_JIRA.md new file mode 100644 index 0000000..84bf9a1 --- /dev/null +++ b/examples/README_ATLASSIAN_JIRA.md @@ -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 diff --git a/examples/mcp_settings_atlassian_jira.json b/examples/mcp_settings_atlassian_jira.json new file mode 100644 index 0000000..3442651 --- /dev/null +++ b/examples/mcp_settings_atlassian_jira.json @@ -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 + } + ] +}