Jeffallan/claude-skills / skills/atlassian-mcp
atlassian-mcp
VerifiedIntegrates with Atlassian products to manage project tracking and documentation via MCP protocol. Use when querying Jira issues with JQL filters, creating and updating tickets with custom fields, searching or editing Confluence pages with CQL, managing sprints and backlogs, setting up MCP server authentication, syncing documentation, or debugging Atlassian API integrations.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.4 KB |
| references/authentication-patterns.md | markdown | 13.1 KB |
| references/common-workflows.md | markdown | 18.4 KB |
| references/confluence-operations.md | markdown | 12.4 KB |
| references/jira-queries.md | markdown | 12.3 KB |
| references/mcp-server-setup.md | markdown | 12.4 KB |
references/authentication-patterns.md
View on GitHub# Authentication Patterns
---
## Authentication Methods Overview
| Method | Platform | Use Case | Security Level |
|--------|----------|----------|----------------|
| OAuth 2.1 | Cloud | User-facing apps, integrations | Highest |
| API Token | Cloud | Personal automation, scripts | Medium |
| PAT | Server/DC | Server integrations | Medium |
| Basic Auth | Legacy | Deprecated, avoid | Low |
## OAuth 2.1 (Atlassian Cloud)
### Authorization Code Flow
For applications that act on behalf of users.
**Step 1: Register Your App**
1. Go to [developer.atlassian.com](https://developer.atlassian.com/console/myapps/)
2. Create new app
3. Configure OAuth 2.0 (3LO)
4. Add callback URL
5. Request necessary scopes
**Step 2: Authorization Request**
```typescript
const authUrl = new URL('https://auth.atlassian.com/authorize');
authUrl.searchParams.set('audience', 'api.atlassian.com');
authUrl.searchParams.set('client_id', CLIENT_ID);
authUrl.searchParams.set('scope', 'read:jira-work write:jira-work read:confluence-content.all write:confluence-content');
authUrl.searchParams.set('redirect_uri', REDIRECT_URI);
authUrl.searchParams.set('state', generateState());
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('prompt', 'consent');
// Redirect user to authUrl.toString()
```
**Step 3: Exchange Code for Token**
```typescript
async function exchangeCodeForToken(code: string): Promise<TokenResponse> {
const response = await fetch('https://auth.atlassian.com/oauth/token', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
grant_type: 'authorization_code',
client_id: CLIENT_ID,
client_secret: CLIENT_SECRET,
code,
redirect_uri: REDIRECT_URI,
}),
});
if (!response.ok) {
throw new Error(`Token exchange failed: ${response.statusText}`);
}
return response.json();
}
interface TokenResponse {
access_token: string;
refresh_token: string;
expires_in: number;
scope: string;
token_type: 'Bearer';
}
```
**Step 4: Refresh Token**
```typescript
async function refreshAccessToken(refreshToken: string): Promise<TokenResponse> {
const response = await fetch('https://auth.atlassian.com/oauth/token', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
grant_type: 'refresh_token',
client_id: CLIENT_ID,
client_secret: CLIENT_SECRET,
refresh_token: refreshToken,
}),
});
return response.json();
}
```
**Step 5: Get Accessible Resources**
```typescript
async function getAccessibleResources(accessToken: string): Promise<Resource[]> {
const response = await fetch(
'https://api.atlassian.com/oauth/token/accessible-resources',
{
headers: {
Authorization: `Bearer ${accessToken}`,
Accept: 'application/json',
},
}
);
return response.json();
}
interface Resource {
id: string; // Cloud ID
name: string; // Site name
url: string; // https://your-site.atlassian.net
scopes: string[];
avatarUrl: string;
}
```
### OAuth Scopes Reference
**Jira Scopes:**
| Scope | Description |
|-------|-------------|
| `read:jira-work` | Read issues, projects, boards |
| `write:jira-work` | Create/update issues |
| `manage:jira-project` | Manage project settings |
| `manage:jira-configuration` | Manage global settings |
| `read:jira-user` | Read user profiles |
| `manage:jira-data-provider` | Data provider integrations |
**Confluence Scopes:**
| Scope | Description |
|-------|-------------|
| `read:confluence-content.all` | Read all content |
| `write:confluence-content` | Create/update content |
| `read:confluence-content.summary` | Read content summaries |
| `read:confluence-space.summary` | Read space summaries |
| `write:confluence-space` | Create/manage spaces |
| `read:confluence-user` | Read user profiles |
**Granular Scopes (v2):**
```
read:issue-details:jira
write:issue:jira
read:sprint:jira-software
write:sprint:jira-software
read:page:confluence
write:page:confluence
read:comment:confluence
write:comment:confluence
```
## API Tokens (Atlassian Cloud)
### Creating API Token
1. Go to [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Click "Create API token"
3. Give it a descriptive label
4. Copy token immediately (shown only once)
### Using API Token
```typescript
// Basic authentication with API token
const credentials = Buffer.from(`${email}:${apiToken}`).toString('base64');
const response = await fetch('https://your-site.atlassian.net/rest/api/3/myself', {
headers: {
Authorization: `Basic ${credentials}`,
Accept: 'application/json',
},
});
// For MCP server configuration
const config = {
JIRA_URL: 'https://your-site.atlassian.net',
JIRA_USERNAME: 'your-email@company.com',
JIRA_API_TOKEN: '<jira-api-token>',
};
```
### Token Security Best Practices
```typescript
// Store tokens securely
import { SecretManagerServiceClient } from '@google-cloud/secret-manager';
import { SecretsManager } from '@aws-sdk/client-secrets-manager';
// Option 1: Environment variables (development only)
const token = process.env.ATLASSIAN_API_TOKEN;
// Option 2: GCP Secret Manager
async function getTokenFromGCP(secretName: string): Promise<string> {
const client = new SecretManagerServiceClient();
const [version] = await client.accessSecretVersion({
name: `projects/my-project/secrets/${secretName}/versions/latest`,
});
return version.payload?.data?.toString() || '';
}
// Option 3: AWS Secrets Manager
async function getTokenFromAWS(secretName: string): Promise<string> {
const client = new SecretsManager({ region: 'us-east-1' });
const response = await client.getSecretValue({ SecretId: secretName });
return response.SecretString || '';
}
// Option 4: HashiCorp Vault
async function getTokenFromVault(path: string): Promise<string> {
const response = await fetch(`${VAULT_ADDR}/v1/${path}`, {
headers: { 'X-Vault-Token': VAULT_TOKEN },
});
const data = await response.json();
return data.data.data.token;
}
```
## Personal Access Tokens (Server/Data Center)
### Creating PAT
**Jira Server/DC:**
1. Profile > Personal Access Tokens
2. Create token
3. Set expiration date
4. Select permissions
**Confluence Server/DC:**
1. Profile > Settings > Personal Access Tokens
2. Create token
3. Configure permissions
### Using PAT
```typescript
// Bearer token authentication
const response = await fetch('https://jira.internal.company.com/rest/api/2/myself', {
headers: {
Authorization: `Bearer ${personalAccessToken}`,
Accept: 'application/json',
},
});
// MCP server configuration
const config = {
JIRA_URL: 'https://jira.internal.company.com',
JIRA_PERSONAL_TOKEN: '<jira-personal-access-token>',
};
```
### PAT Permissions
| Permission | Jira | Confluence |
|------------|------|------------|
| Read | Browse projects, view issues | View pages |
| Write | Create/edit issues | Create/edit pages |
| Admin | Project administration | Space administration |
## Token Management
### Token Lifecycle Manager
```typescript
interface TokenInfo {
accessToken: string;
refreshToken?: string;
expiresAt: Date;
scopes: string[];
}
class TokenManager {
private tokenInfo: TokenInfo | null = null;
private refreshThreshold = 5 * 60 * 1000; // 5 minutes
async getValidToken(): Promise<string> {
if (!this.tokenInfo) {
throw new Error('Not authenticated');
}
// Check if token needs refresh
const timeUntilExpiry = this.tokenInfo.expiresAt.getTime() - Date.now();
if (timeUntilExpiry < this.refreshThreshold) {
await this.refreshToken();
}
return this.tokenInfo.accessToken;
}
private async refreshToken(): Promise<void> {
if (!this.tokenInfo?.refreshToken) {
throw new Error('No refresh token available');
}
const response = await refreshAccessToken(this.tokenInfo.refreshToken);
this.tokenInfo = {
accessToken: response.access_token,
refreshToken: response.refresh_token || this.tokenInfo.refreshToken,
expiresAt: new Date(Date.now() + response.expires_in * 1000),
scopes: response.scope.split(' '),
};
}
isAuthenticated(): boolean {
return this.tokenInfo !== null && this.tokenInfo.expiresAt > new Date();
}
getScopes(): string[] {
return this.tokenInfo?.scopes || [];
}
hasScope(scope: string): boolean {
return this.getScopes().includes(scope);
}
}
```
### Token Rotation Strategy
```typescript
class TokenRotationManager {
private rotationInterval = 30 * 24 * 60 * 60 * 1000; // 30 days
async checkAndRotate(tokenCreatedAt: Date): Promise<boolean> {
const age = Date.now() - tokenCreatedAt.getTime();
if (age > this.rotationInterval) {
console.warn('API token is due for rotation');
return true;
}
return false;
}
async sendRotationReminder(email: string, tokenLabel: string): Promise<void> {
// Integrate with your notification system
await sendEmail({
to: email,
subject: 'Atlassian API Token Rotation Reminder',
body: `Your API token "${tokenLabel}" is due for rotation.
Please create a new token and update your integrations.`,
});
}
}
```
## Permission Verification
### Check Current Permissions
```typescript
async function verifyPermissions(
client: MCPClient,
requiredOperations: string[]
): Promise<PermissionReport> {
const report: PermissionReport = {
hasAllPermissions: true,
details: [],
};
for (const operation of requiredOperations) {
try {
switch (operation) {
case 'read:jira':
await client.callTool({
name: 'jira_get_issue',
arguments: { issue_key: 'TEST-1' },
});
break;
case 'write:jira':
// Create and immediately delete a test issue
const created = await client.callTool({
name: 'jira_create_issue',
arguments: {
project_key: 'TEST',
issue_type: 'Task',
summary: '[Permission Test] Delete me',
},
});
// Clean up
await client.callTool({
name: 'jira_delete_issue',
arguments: { issue_key: JSON.parse(created.content[0].text).key },
});
break;
case 'read:confluence':
await client.callTool({
name: 'confluence_search',
arguments: { cql: 'type = page', limit: 1 },
});
break;
}
report.details.push({ operation, status: 'granted' });
} catch (error: any) {
report.hasAllPermissions = false;
report.details.push({
operation,
status: 'denied',
error: error.message,
});
}
}
return report;
}
```
## Security Checklist
### Do:
- Use OAuth 2.1 for user-facing applications
- Store secrets in dedicated secrets management systems
- Implement token rotation policies
- Use minimal required scopes
- Log authentication events (without secrets)
- Implement rate limiting at application level
- Validate tokens before use
### Don't:
- Hardcode tokens in source code
- Log tokens or secrets
- Share tokens between environments
- Use Basic Auth (deprecated)
- Request more scopes than needed
- Store tokens in browser localStorage
- Commit `.env` files with real credentials
### Environment Configuration Template
```bash
# .env.example (commit this)
ATLASSIAN_SITE_URL=https://your-site.atlassian.net
ATLASSIAN_AUTH_TYPE=oauth # or 'api_token' or 'pat'
# OAuth settings (if using OAuth)
ATLASSIAN_CLIENT_ID=
ATLASSIAN_CLIENT_SECRET=
# API Token settings (if using API token)
ATLASSIAN_USERNAME=
ATLASSIAN_API_TOKEN=
# PAT settings (if using Server/DC)
ATLASSIAN_PERSONAL_TOKEN=
```
```bash
# .gitignore
.env
.env.local
.env.*.local
credentials.json
**/secrets/**
```
## Troubleshooting
### Common Authentication Errors
**401 Unauthorized:**
- Invalid or expired token
- Wrong authentication method
- Missing Authorization header
**403 Forbidden:**
- Token valid but lacks required scope
- Resource-level permission denied
- IP allowlist blocking request
**Token refresh fails:**
- Refresh token expired (after 90 days of inactivity)
- Client secret changed
- App permissions revoked
### Debug Authentication
```typescript
async function debugAuth(token: string): Promise<void> {
// Check token validity
const meResponse = await fetch(
'https://api.atlassian.com/me',
{ headers: { Authorization: `Bearer ${token}` } }
);
console.log('Token status:', meResponse.status);
if (meResponse.ok) {
const me = await meResponse.json();
console.log('Authenticated as:', me.email);
}
// Check accessible resources
const resourcesResponse = await fetch(
'https://api.atlassian.com/oauth/token/accessible-resources',
{ headers: { Authorization: `Bearer ${token}` } }
);
if (resourcesResponse.ok) {
const resources = await resourcesResponse.json();
console.log('Accessible sites:', resources.map((r: any) => r.name));
}
}
```
## Related References
- `mcp-server-setup.md` - Server configuration with credentials
- `jira-queries.md` - Operations that require authentication
- `confluence-operations.md` - Content operations with auth
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |