Transform how you manage and track your work by connecting Claude, Cursor AI, and other AI assistants directly to your Jira projects, issues, and workflows. Get instant project insights, streamline issue management, and enhance your team collaboration. - Ask AI about your projects: "What are the active issues in the DEV project?" - Get issue insights: "Show me details about PROJ-123 including comm
Add this skill
npx mdskills install aashari/mcp-server-atlassian-jiraWell-documented MCP server with comprehensive API coverage, clear setup instructions, and useful examples
1# Connect AI to Your Jira Projects23Transform how you manage and track your work by connecting Claude, Cursor AI, and other AI assistants directly to your Jira projects, issues, and workflows. Get instant project insights, streamline issue management, and enhance your team collaboration.45[](https://www.npmjs.com/package/@aashari/mcp-server-atlassian-jira)67## What You Can Do89- **Ask AI about your projects**: "What are the active issues in the DEV project?"10- **Get issue insights**: "Show me details about PROJ-123 including comments"11- **Track project progress**: "List all high priority issues assigned to me"12- **Manage issue comments**: "Add a comment to PROJ-456 about the test results"13- **Search across projects**: "Find all bugs in progress across my projects"14- **Create and update issues**: "Create a new bug in the MOBILE project"1516## Perfect For1718- **Developers** who need quick access to issue details and development context19- **Project Managers** tracking progress, priorities, and team assignments20- **Scrum Masters** managing sprints and workflow states21- **Team Leads** monitoring project health and issue resolution22- **QA Engineers** tracking bugs and testing status23- **Anyone** who wants to interact with Jira using natural language2425## Quick Start2627Get up and running in 2 minutes:2829### 1. Get Your Jira Credentials3031Generate a Jira API Token:321. Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)332. Click **Create API token**343. Give it a name like **"AI Assistant"**354. **Copy the generated token** immediately (you won't see it again!)3637### 2. Try It Instantly3839```bash40# Set your credentials41export ATLASSIAN_SITE_NAME="your-company" # for your-company.atlassian.net42export ATLASSIAN_USER_EMAIL="your.email@company.com"43export ATLASSIAN_API_TOKEN="your_api_token"4445# List your Jira projects46npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/project/search"4748# Get details about a specific project49npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/project/DEV"5051# Get an issue with JMESPath filtering52npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/issue/PROJ-123" --jq "{key: key, summary: fields.summary, status: fields.status.name}"53```5455## Connect to AI Assistants5657### For Claude Desktop Users5859Add this to your Claude configuration file (`~/.claude/claude_desktop_config.json`):6061```json62{63 "mcpServers": {64 "jira": {65 "command": "npx",66 "args": ["-y", "@aashari/mcp-server-atlassian-jira"],67 "env": {68 "ATLASSIAN_SITE_NAME": "your-company",69 "ATLASSIAN_USER_EMAIL": "your.email@company.com",70 "ATLASSIAN_API_TOKEN": "your_api_token"71 }72 }73 }74}75```7677Restart Claude Desktop, and you'll see the jira server in the status bar.7879### For Other AI Assistants8081Most AI assistants support MCP. Install the server globally:8283```bash84npm install -g @aashari/mcp-server-atlassian-jira85```8687Then configure your AI assistant to use the MCP server with STDIO transport.8889### Alternative: Configuration File9091Create `~/.mcp/configs.json` for system-wide configuration:9293```json94{95 "jira": {96 "environments": {97 "ATLASSIAN_SITE_NAME": "your-company",98 "ATLASSIAN_USER_EMAIL": "your.email@company.com",99 "ATLASSIAN_API_TOKEN": "your_api_token"100 }101 }102}103```104105**Alternative config keys:** The system also accepts `"atlassian-jira"`, `"@aashari/mcp-server-atlassian-jira"`, or `"mcp-server-atlassian-jira"` instead of `"jira"`.106107## Available Tools108109This MCP server provides 5 generic tools that can access any Jira API endpoint:110111| Tool | Description |112|------|-------------|113| `jira_get` | GET any Jira API endpoint (read data) |114| `jira_post` | POST to any endpoint (create resources) |115| `jira_put` | PUT to any endpoint (replace resources) |116| `jira_patch` | PATCH any endpoint (partial updates) |117| `jira_delete` | DELETE any endpoint (remove resources) |118119### Common API Paths120121**Projects:**122- `/rest/api/3/project/search` - List all projects (paginated, recommended)123- `/rest/api/3/project` - List all projects (non-paginated, legacy)124- `/rest/api/3/project/{projectKeyOrId}` - Get project details125126**Issues:**127- `/rest/api/3/search/jql` - Search issues with JQL (use `jql` query param). **IMPORTANT:** `/rest/api/3/search` is deprecated!128- `/rest/api/3/issue/{issueIdOrKey}` - Get issue details129- `/rest/api/3/issue` - Create issue (POST)130- `/rest/api/3/issue/{issueIdOrKey}/transitions` - Get/perform transitions131132**Comments:**133- `/rest/api/3/issue/{issueIdOrKey}/comment` - List/add comments134- `/rest/api/3/issue/{issueIdOrKey}/comment/{commentId}` - Get/update/delete comment135136**Worklogs:**137- `/rest/api/3/issue/{issueIdOrKey}/worklog` - List/add worklogs138- `/rest/api/3/issue/{issueIdOrKey}/worklog/{worklogId}` - Get/update/delete worklog139140**Users & Statuses:**141- `/rest/api/3/myself` - Get current user142- `/rest/api/3/user/search` - Search users (use `query` param)143- `/rest/api/3/status` - List all statuses144- `/rest/api/3/issuetype` - List issue types145- `/rest/api/3/priority` - List priorities146147### TOON Output Format148149By default, all responses use **TOON (Token-Oriented Object Notation)** format, which reduces token usage by 30-60% compared to JSON. TOON uses tabular arrays and minimal syntax, making it ideal for AI consumption.150151**To use JSON instead:** Add `--output-format json` to CLI commands or set `outputFormat: "json"` in MCP tool calls.152153**Example TOON vs JSON:**154```155TOON: key|summary|status156 PROJ-1|First issue|Open157 PROJ-2|Second issue|Done158159JSON: [{"key":"PROJ-1","summary":"First issue","status":"Open"},160 {"key":"PROJ-2","summary":"Second issue","status":"Done"}]161```162163### JMESPath Filtering164165All tools support optional JMESPath (`jq`) filtering to extract specific data:166167```bash168# Get just project names and keys169npx -y @aashari/mcp-server-atlassian-jira get \170 --path "/rest/api/3/project/search" \171 --jq "values[].{key: key, name: name}"172173# Get issue key and summary174npx -y @aashari/mcp-server-atlassian-jira get \175 --path "/rest/api/3/issue/PROJ-123" \176 --jq "{key: key, summary: fields.summary, status: fields.status.name}"177```178179### Response Truncation and Raw Logs180181For large API responses (>40k characters ≈ 10k tokens), responses are automatically truncated with guidance. The complete raw response is saved to `/tmp/mcp/mcp-server-atlassian-jira/<timestamp>-<random>.txt` for reference.182183**When truncated, you'll see:**184- A truncation notice with the raw file path185- Suggestions to refine your query with better filters186- Percentage of data shown vs total size187188## Real-World Examples189190### Explore Your Projects191192Ask your AI assistant:193- *"List all projects I have access to"*194- *"Show me details about the DEV project"*195- *"What projects contain the word 'Platform'?"*196197### Search and Track Issues198199Ask your AI assistant:200- *"Find all high priority issues in the DEV project"*201- *"Show me issues assigned to me that are in progress"*202- *"Search for bugs reported in the last week"*203- *"List all open issues for the mobile team"*204205### Manage Issue Details206207Ask your AI assistant:208- *"Get full details about issue PROJ-456 including comments"*209- *"What's the current status and assignee of PROJ-123?"*210- *"Display all comments on the authentication bug"*211212### Issue Communication213214Ask your AI assistant:215- *"Add a comment to PROJ-456: 'Code review completed, ready for testing'"*216- *"Comment on the login issue that it's been deployed to staging"*217218## CLI Commands219220The CLI mirrors the MCP tools for direct terminal access:221222```bash223# GET request (returns TOON format by default)224npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/project/search"225226# GET with query parameters and JSON output227npx -y @aashari/mcp-server-atlassian-jira get \228 --path "/rest/api/3/search/jql" \229 --query-params '{"jql": "project=DEV AND status=\"In Progress\"", "maxResults": "10"}' \230 --output-format json231232# GET with JMESPath filtering to extract specific fields233npx -y @aashari/mcp-server-atlassian-jira get \234 --path "/rest/api/3/issue/PROJ-123" \235 --jq "{key: key, summary: fields.summary, status: fields.status.name}"236237# POST request (create an issue)238npx -y @aashari/mcp-server-atlassian-jira post \239 --path "/rest/api/3/issue" \240 --body '{"fields": {"project": {"key": "DEV"}, "summary": "New issue title", "issuetype": {"name": "Task"}}}'241242# POST request (add a comment)243npx -y @aashari/mcp-server-atlassian-jira post \244 --path "/rest/api/3/issue/PROJ-123/comment" \245 --body '{"body": {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": "My comment"}]}]}}'246247# PUT request (update issue - full replacement)248npx -y @aashari/mcp-server-atlassian-jira put \249 --path "/rest/api/3/issue/PROJ-123" \250 --body '{"fields": {"summary": "Updated title"}}'251252# PATCH request (partial update)253npx -y @aashari/mcp-server-atlassian-jira patch \254 --path "/rest/api/3/issue/PROJ-123" \255 --body '{"fields": {"summary": "Updated title"}}'256257# DELETE request258npx -y @aashari/mcp-server-atlassian-jira delete \259 --path "/rest/api/3/issue/PROJ-123/comment/12345"260```261262**Note:** All CLI commands support:263- `--output-format` - Choose between `toon` (default, token-efficient) or `json`264- `--jq` - Filter response with JMESPath expressions265- `--query-params` - Pass query parameters as JSON string266267## Troubleshooting268269### "Authentication failed" or "403 Forbidden"2702711. **Check your API Token permissions**:272 - Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)273 - Make sure your token is still active and hasn't expired2742752. **Verify your site name format**:276 - If your Jira URL is `https://mycompany.atlassian.net`277 - Your site name should be just `mycompany`2782793. **Test your credentials**:280 ```bash281 npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/myself"282 ```283284### "Resource not found" or "404"2852861. **Check the API path**:287 - Paths are case-sensitive288 - Use project keys (e.g., `DEV`) not project names289 - Issue keys include the project prefix (e.g., `DEV-123`)2902912. **Verify access permissions**:292 - Make sure you have access to the project in your browser293 - Some projects may be restricted to certain users294295### "No results found" when searching2962971. **Try different search terms**:298 - Use project keys instead of project names299 - Try broader search criteria3003012. **Check JQL syntax**:302 - Validate your JQL in Jira's advanced search first303304### Claude Desktop Integration Issues3053061. **Restart Claude Desktop** after updating the config file3072. **Verify config file location**:308 - macOS: `~/.claude/claude_desktop_config.json`309 - Windows: `%APPDATA%\Claude\claude_desktop_config.json`310311### Getting Help312313If you're still having issues:3141. Run a simple test command to verify everything works3152. Check the [GitHub Issues](https://github.com/aashari/mcp-server-atlassian-jira/issues) for similar problems3163. Create a new issue with your error message and setup details317318## Frequently Asked Questions319320### What permissions do I need?321322Your Atlassian account needs:323- **Access to Jira** with the appropriate permissions for the projects you want to query324- **API token** with appropriate permissions (automatically granted when you create one)325326### Can I use this with Jira Server (on-premise)?327328Currently, this tool only supports **Jira Cloud**. Jira Server/Data Center support may be added in future versions.329330### How do I find my site name?331332Your site name is the first part of your Jira URL:333- URL: `https://mycompany.atlassian.net` -> Site name: `mycompany`334- URL: `https://acme-corp.atlassian.net` -> Site name: `acme-corp`335336### What AI assistants does this work with?337338Any AI assistant that supports the Model Context Protocol (MCP):339- Claude Desktop340- Cursor AI341- Continue.dev342- Many others343344### Is my data secure?345346Yes! This tool:347- Runs entirely on your local machine348- Uses your own Jira credentials349- Never sends your data to third parties350- Only accesses what you give it permission to access351352### Can I search across multiple projects?353354Yes! Use JQL queries for cross-project searches. For example:355```bash356npx -y @aashari/mcp-server-atlassian-jira get \357 --path "/rest/api/3/search/jql" \358 --query-params '{"jql": "assignee=currentUser() AND status=\"In Progress\""}'359```360361## Technical Details362363### Recent Updates364365**Version 3.2.1** (December 2025):366- Added TOON output format for 30-60% token reduction367- Implemented automatic response truncation for large payloads (>40k chars)368- Raw API responses saved to `/tmp/mcp/mcp-server-atlassian-jira/` for reference369- Updated to MCP SDK v1.23.0 with modern `registerTool` API370- Fixed deprecated `/rest/api/3/search` endpoint (now use `/rest/api/3/search/jql`)371- Updated all dependencies to latest versions (Zod v4.1.13, Commander v14.0.2)372373### Requirements374375- **Node.js**: 18.0.0 or higher376- **MCP SDK**: v1.23.0 (uses modern registration APIs)377- **Jira**: Cloud only (Server/Data Center not supported)378379### Architecture380381This server follows the 5-layer MCP architecture:3821. **CLI Layer** - Human interface using Commander.js3832. **Tools Layer** - AI interface with Zod validation3843. **Controllers Layer** - Business logic and orchestration3854. **Services Layer** - Direct Jira REST API calls3865. **Utils Layer** - Cross-cutting concerns (logging, formatting, transport)387388### Debugging389390Enable debug logging by setting the `DEBUG` environment variable:391392```bash393# In Claude Desktop config394{395 "mcpServers": {396 "jira": {397 "command": "npx",398 "args": ["-y", "@aashari/mcp-server-atlassian-jira"],399 "env": {400 "DEBUG": "true",401 "ATLASSIAN_SITE_NAME": "your-company",402 "ATLASSIAN_USER_EMAIL": "your.email@company.com",403 "ATLASSIAN_API_TOKEN": "your_api_token"404 }405 }406 }407}408```409410Debug logs are written to `~/.mcp/data/mcp-server-atlassian-jira.<session-id>.log`411412**Check raw API responses:** When responses are truncated, the full raw response is saved to `/tmp/mcp/mcp-server-atlassian-jira/<timestamp>-<random>.txt` with request/response details.413414## Migration from v2.x415416Version 3.0 replaces 8+ specific tools with 5 generic HTTP method tools. If you're upgrading from v2.x:417418**Before (v2.x):**419```420jira_ls_projects, jira_get_project, jira_ls_issues, jira_get_issue,421jira_create_issue, jira_ls_comments, jira_add_comment, jira_ls_statuses, ...422```423424**After (v3.0+):**425```426jira_get, jira_post, jira_put, jira_patch, jira_delete427```428429**Migration examples:**430- `jira_ls_projects` -> `jira_get` with path `/rest/api/3/project/search`431- `jira_get_project` -> `jira_get` with path `/rest/api/3/project/{key}`432- `jira_get_issue` -> `jira_get` with path `/rest/api/3/issue/{key}`433- `jira_create_issue` -> `jira_post` with path `/rest/api/3/issue`434- `jira_add_comment` -> `jira_post` with path `/rest/api/3/issue/{key}/comment`435- `jira_ls_statuses` -> `jira_get` with path `/rest/api/3/status`436437**Benefits of v3.0+:**438- Full access to any Jira REST API v3 endpoint (not just predefined tools)439- JMESPath filtering for efficient data extraction440- Consistent interface across all HTTP methods441- TOON format for 30-60% token savings442- Automatic response truncation with raw file logging443444## Support445446Need help? Here's how to get assistance:4474481. **Check the troubleshooting section above** - most common issues are covered there4492. **Visit our GitHub repository** for documentation and examples: [github.com/aashari/mcp-server-atlassian-jira](https://github.com/aashari/mcp-server-atlassian-jira)4503. **Report issues** at [GitHub Issues](https://github.com/aashari/mcp-server-atlassian-jira/issues)4514. **Start a discussion** for feature requests or general questions452453---454455*Made with care for teams who want to bring AI into their project management workflow.*456
Full transparency — inspect the skill content before installing.