jira

This MCP server exposes a set of JIRA-related tools that let AI assistants interact with a JIRA instance via the MCP protocol. The available tools include jira_get_issue to fetch details of a specific issue by key, jira_search to query issues using JQL with pagination, jira_create_issue to create new issues with required fields and optional ones, jira_update_issue to modify fields like summary or description, jira_transition_issue to move an issue to a new status with an optional comment, and jira_add_comment to append a comment to an existing issue. To use these tools, provide a JSON payload specifying the tool name and the arguments (for example, an issue key, JQL query, or issue fields). The server authenticates using a bearer token (JIRA_API_TOKEN) and reads the JIRA_BASE_URL to determine which JIRA instance to operate on. Ensure you have configured the environment variables (JIRA_BASE_URL and JIRA_API_TOKEN) before issuing tool calls. The README examples demonstrate typical tool invocations for common actions like searching issues, reading an issue, creating an issue, updating fields, and adding comments. Additionally, you can run the server locally with npm start or directly with node server.js if you’re developing or testing.

Prerequisites:

• Node.js 18.0 or higher
• npm (comes with Node.js)
• Access to a JIRA instance with API token credentials

Installation steps:

1. Install dependencies and install the package locally (from source):

   • git clone <repository-url>
   • cd jira-mcp
   • npm install

2. Configure environment variables (preferred via a .env file):

   • JIRA_BASE_URL=https://your-jira-instance.com
   • JIRA_API_TOKEN=your-api-token
   • JIRA_EMAIL=your-email@domain.com (optional)

3. Start the server:

   • npm start
   • Or run directly: node server.js

4. (Optional) Quick Start with npx without installation:

   • npx @hackdonalds/jira-mcp

5. If you installed globally:

   • npm install -g @hackdonalds/jira-mcp
   • jira-mcp

Tips and tips:

• Ensure JIRA_BASE_URL points to the correct instance (cloud or server) and does not include a trailing slash.
• JIRA_API_TOKEN must be a valid personal access token with appropriate permissions for the actions you intend (read, write, comment, transition).
• The server uses Bearer token authentication; JIRA_EMAIL is optional and used for logging purposes only.
• If you encounter authentication errors (401), verify token scope and that the JIRA URL is accessible from your network.
• For file logging issues on restricted environments, the server is designed to gracefully fallback to stderr; check mcp.log if it’s created.
• Compatible with Atlassian Cloud, JIRA Server 9.0+, and Data Center installations via the REST API v2 at /rest/api/2/.
• If you need to adjust runtime behavior, review the environment variable configuration and .env example in the project.