Jira MCP Server

A Model Context Protocol (MCP) server that allows Claude and other AI assistants to create and manage Jira issues.

Installation

1. Clone this repository
2. Install dependencies:

cd jira_mcp_server
npm install

Configuration

The server requires the following environment variables:

• JIRA_SERVER: Your Jira server URL (defaults to 'https://alepo.atlassian.net')
• JIRA_USER: Your Jira email address
• JIRA_TOKEN: Your Jira API token
• JIRA_PROJECTS: Comma-separated list of project keys that are allowed for issue creation (e.g., XYZ,ABC,DEF)
  • The server will only return these projects in get_jira_projects and will only allow creating issues in these projects
  • Must contain at least one project key

You can set these in a .env file or through your MCP configuration.

Jira API Token

To create a Jira API token:

1. Log in to https://id.atlassian.com
2. Go to Security → API tokens
3. Click "Create API token"
4. Give it a name like "MCP Server" and click "Create"
5. Copy the token and use it for your JIRA_TOKEN environment variable

Jira Permissions

The user associated with the API token must have:

• Read access to projects you want to list
• Create issue permissions for projects you want to create tickets in

If you encounter errors like "You do not have permission to create issues in this project", make sure your Jira user has the necessary permissions.

MCP Configuration Example

Add this to your MCP configuration:

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": [
        "server.js"
      ],
      "cwd": "/path/to/jira_mcp_server",
      "env": {
        "JIRA_SERVER": "https://alepo.atlassian.net",
        "JIRA_USER": "your-jira-email@example.com",
        "JIRA_TOKEN": "your-jira-api-token",
        "JIRA_PROJECTS": "XYZ,ABC,DEF"
      }
    }
  }
}

Running the Server

npm start

Using with Claude or Other AI Assistants

This server implements the Model Context Protocol (MCP), which allows AI assistants like Claude to directly interact with Jira. Once the server is running, Claude can use the provided tools to create tickets and retrieve project information.

For example, when Claude is configured with this MCP server, it can run commands like:

• "Create a Jira ticket for the bug we just discussed"
• "Show me all available Jira projects"

The AI will be restricted to creating issues only in the projects specified in the JIRA_PROJECTS environment variable.

Available Tools

create_jira_issue

Creates a new Jira issue with the specified parameters.

Parameters:

• project: Jira project key (e.g., CRMUP)
• summary: Issue summary/title
• description: Detailed description of the issue
• issuetype: Type of issue (e.g., Bug, Task, Story) - defaults to "Task"
• priority: Priority of the issue (e.g., High, Medium, Low) - defaults to "Medium"

Example success response:

{
  "success": true,
  "key": "CRMUP-123",
  "id": "10042",
  "url": "https://alepo.atlassian.net/browse/CRMUP-123"
}

Example error response when project is not in allowed list:

{
  "success": false,
  "error": "Project TEST is not allowed. Only the following projects can be used: XYZ, ABC, DEF"
}

get_jira_projects

Gets a list of available Jira projects. Only returns projects that match the keys specified in the JIRA_PROJECTS environment variable.

No parameters required.

Example response:

{
  "success": true,
  "projects": [
    {
      "id": "10000",
      "key": "XYZ",
      "name": "Project XYZ"
    }
  ]
}

Development

This server is built using:

• The Model Context Protocol TypeScript SDK
• Jira API client for Node.js

For testing and debugging, you can run the example usage script:

node example-usage.js

Troubleshooting

Empty Projects List

If get_jira_projects returns an empty array, check:

1. Your Jira user has permission to view the projects specified in JIRA_PROJECTS
2. The project keys in JIRA_PROJECTS exist in your Jira instance
3. Your API token hasn't expired

Permission Errors

If you get "You do not have permission to create issues in this project" errors:

1. Verify your Jira user has the "Create Issue" permission for that project
2. Try creating an issue manually with the same account to confirm permissions
3. If using a cloud instance, make sure your user is properly assigned to the project

Project Not Allowed Errors

If you get "Project X is not allowed" errors:

1. Check that the project key you're trying to use is included in your JIRA_PROJECTS environment variable
2. Make sure the project keys in JIRA_PROJECTS are correctly spelled and match your Jira projects exactly (case-sensitive)
3. If you need to use additional projects, update your JIRA_PROJECTS environment variable