Atlassian Jira MCP Server
About
This project is a customizable Model Context Protocol (MCP) server written in TypeScript, designed to extend AI assistants like Claude or Cursor with access to Atlassian Jira data. MCP is an open-source protocol by Anthropic for connecting AI systems to external capabilities securely and efficiently. For more details on MCP, see https://modelcontextprotocol.io/docs/. This server allows AI assistants to access projects and issues directly from your organization's Jira instance.
Project Features
- MCP Server : Exposes Jira tools and resources to AI clients (e.g., Claude Desktop, Cursor AI) via STDIO or HTTP.
- Jira Integration : Access projects and issues from your Jira instance.
- CLI Support : Run Jira queries directly from the command line without an AI client.
- Flexible Configuration : Supports direct environment variables for quick use or a global config file at
$HOME/.mcp/configs.json for managing multiple servers.
- Development Tools : Built-in MCP Inspector for debugging, plus testing and linting utilities.
Available Tools
list-projects : Get a list of all available Jira projects with optional filtering.get-project : Retrieve detailed information about a specific project by ID or key.list-issues : List issues with optional JQL filtering.get-issue : Retrieve detailed information about a specific issue by ID or key.
User Guide
Configuration Options
- DEBUG : Set to
true for detailed logging (default: false).
- ATLASSIAN_SITE_NAME : Your Atlassian site name (e.g.,
your-instance for your-instance.atlassian.net) – required.
- ATLASSIAN_USER_EMAIL : Your Atlassian account email address – required.
- ATLASSIAN_API_TOKEN : API token for Atlassian API access – required.
Method 1: Environment Variables
Pass configs directly when running:
DEBUG=true ATLASSIAN_SITE_NAME=your-instance [[email protected]](/cdn-cgi/l/email-protection) ATLASSIAN_API_TOKEN=your_token npx -y @aashari/mcp-server-atlassian-jira
Method 2: Global Config File (Recommended)
Create $HOME/.mcp/configs.json:
{
"@aashari/mcp-server-atlassian-jira": {
"environments": {
"DEBUG": "true",
"ATLASSIAN_SITE_NAME": "your-instance",
"ATLASSIAN_USER_EMAIL": "[[email protected]](/cdn-cgi/l/email-protection)",
"ATLASSIAN_API_TOKEN": "your_api_token"
}
}
}
You can also configure multiple MCP servers in the same file:
{
"@aashari/boilerplate-mcp-server": {
"environments": {
"DEBUG": "true",
"IPAPI_API_TOKEN": "your_token"
}
},
"@aashari/mcp-server-atlassian-confluence": {
"environments": {
"DEBUG": "true",
"ATLASSIAN_SITE_NAME": "your-instance",
"ATLASSIAN_USER_EMAIL": "[[email protected]](/cdn-cgi/l/email-protection)",
"ATLASSIAN_API_TOKEN": "your_api_token"
}
},
"@aashari/mcp-server-atlassian-jira": {
"environments": {
"DEBUG": "true",
"ATLASSIAN_SITE_NAME": "your-instance",
"ATLASSIAN_USER_EMAIL": "[[email protected]](/cdn-cgi/l/email-protection)",
"ATLASSIAN_API_TOKEN": "your_api_token"
}
}
}
Using with Claude Desktop
- Open Settings :
* Launch Claude Desktop, click the gear icon (top-right).
- Edit Config :
* Click "Edit Config" to open claude_desktop_config.json (e.g., ~/Library/Application Support/Claude on macOS or %APPDATA%\Claude on Windows).
* Click "Edit Config" to open claude_desktop_config.json (e.g., ~/Library/Application Support/Claude on macOS or %APPDATA%\Claude on Windows).
- Add Server :
* Use the global config file (recommended):
{
"mcpServers": {
"aashari/mcp-server-atlassian-jira": {
"command": "npx",
"args": ["-y", "@aashari/mcp-server-atlassian-jira"]
}
}
}
* Or configure directly:
{
"mcpServers": {
"aashari/mcp-server-atlassian-jira": {
"command": "npx",
"args": [
"-y",
"DEBUG=true",
"ATLASSIAN_SITE_NAME=your-instance",
"[[email protected]](/cdn-cgi/l/email-protection)",
"ATLASSIAN_API_TOKEN=your_token",
"@aashari/mcp-server-atlassian-jira"
]
}
}
}
- Restart : Close and reopen Claude Desktop.
- Test : Click the hammer icon, verify Jira tools are listed, then ask: "List my Jira projects" or "Show me details for issue PROJ-123."
Using with Cursor AI
- Open Settings :
* Launch Cursor, press CMD + SHIFT + P (or CTRL + SHIFT + P), select "Cursor Settings" > "MCP".
- Add Server :
* Click "+ Add new MCP server".
* Name : aashari/mcp-server-atlassian-jira.
* Type : command.
* Command :
- Global config:
npx -y @aashari/mcp-server-atlassian-jira.
- Direct:
DEBUG=true ATLASSIAN_SITE_NAME=your-instance [[email protected]](/cdn-cgi/l/email-protection) ATLASSIAN_API_TOKEN=your_token npx -y @aashari/mcp-server-atlassian-jira.
- Verify : Check for a green indicator and Jira tools listed.
- Test : In Agent mode, ask: "Show me open issues in project X" or "Get details for ticket PROJ-456."
Using as a CLI Tool
Run without installation:
# Help
npx -y @aashari/mcp-server-atlassian-jira -- --help
# List projects
npx -y @aashari/mcp-server-atlassian-jira -- list-projects
# Get project details
npx -y @aashari/mcp-server-atlassian-jira -- get-project PROJ
# List issues with JQL
npx -y @aashari/mcp-server-atlassian-jira -- list-issues --jql "project = PROJ AND status = Open"
# Get issue details
npx -y @aashari/mcp-server-atlassian-jira -- get-issue PROJ-123
Or install globally:
npm install -g @aashari/mcp-server-atlassian-jira
Then run:
# Help
mcp-jira --help
# List projects with optional filtering
mcp-jira list-projects --limit 10
# Get a project by ID or key
mcp-jira get-project PROJ
# List issues with optional JQL filtering
mcp-jira list-issues --jql "project = PROJ AND status = Open" --limit 10
# Get an issue by ID or key
mcp-jira get-issue PROJ-123
Use the global config file or prefix with environment variables:
DEBUG=true ATLASSIAN_SITE_NAME=your-instance [[email protected]](/cdn-cgi/l/email-protection) ATLASSIAN_API_TOKEN=your_token mcp-jira list-projects
Developer Guide
Development Scripts
The project includes several scripts for development and production use:
npm run dev:server : Run the server in development mode with MCP Inspector and debug logging.npm run dev:cli : Run CLI commands in development mode with debug logging.npm run start:server : Run the server in production mode with MCP Inspector.npm run start:cli : Run CLI commands in production mode.
Example usage:
# Start the server with Inspector and debug logging
npm run dev:server
# Run a CLI command with debug logging
npm run dev:cli -- list-issues --jql "project = PROJ"
# Start the server with Inspector (no debug)
npm run start:server
# Run a CLI command (no debug)
npm run start:cli -- list-projects
Extending the Project
To add custom tools or resources:
- Services : Add API/data logic in
src/services.
- Controllers : Implement business logic in
src/controllers.
- Tools : Define new tools in
src/tools.
- Resources : Add data sources in
src/resources.
- Register : Update
src/index.ts with your tools/resources.
Additional Development Tools
# Run tests
npm test
# Test coverage
npm run test:coverage
# Lint
npm run lint
# Format
npm run format
MCP Inspector
The MCP Inspector provides a visual interface for debugging and testing your MCP server:
- The Inspector starts your MCP server.
- It launches a web UI (typically at
http://localhost:5173).
- Use the UI to test Jira tools, view requests/responses, and check errors.
Versioning Note
This project follows semantic versioning independently from other MCP servers in the same family (like the Confluence MCP server). Version differences between these projects are expected and reflect their individual development cycles and feature implementations.
License
ISC
