MCP Jira Server for Self-Hosted Jira

A Model Context Protocol (MCP) server for interacting with self-hosted Jira instances using Personal Access Token (PAT) authentication.

Features

✅ Personal Access Token authentication for self-hosted Jira
✅ Create, read, update, and delete Jira issues
✅ Search issues using JQL (Jira Query Language)
✅ Add and view comments
✅ Manage issue assignments
✅ List projects and issue types
✅ Transition issues between statuses
✅ Get current user information

Prerequisites

Node.js 18 or higher
A self-hosted Jira instance (e.g., https://jira.domain.com)
A Jira Personal Access Token

How to Create a Personal Access Token in Self-Hosted Jira

Log in to your Jira instance (e.g., https://jira.domain.com)
Click on your profile icon in the top right corner
Select "Profile" or "Account Settings"
Navigate to "Personal Access Tokens" or "Security"
Click "Create token"
Give your token a name (e.g., "MCP Server")
Set an expiration date (optional but recommended)
Click "Create"
Copy the token immediately - you won't be able to see it again!

Installation

Option 1: Using npm (Recommended)

Direct usage with npx:

npx mcp-jira-server

Or install globally:

npm install -g mcp-jira-server

Option 2: From Source

Clone the repository:

git clone https://github.com/edrich13/mcp-jira-server.git
cd mcp-jira-server

Install dependencies:

npm install

Build the server:

npm run build

Configuration

For Claude Desktop

Add the following to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Option 1: Using npx (Recommended)

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "mcp-jira-server"],
      "env": {
        "JIRA_BASE_URL": "https://jira.domain.com",
        "JIRA_PAT": "your-personal-access-token-here"
      }
    }
  }
}

Option 2: Using source build

{
  "mcpServers": {
    "jira": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/edrich.rocha/.nvm/versions/node/v22.6.0/bin/mcp-jira-server"],
      "env": {
        "JIRA_BASE_URL": "https://jira.domain.com",
        "JIRA_PAT": "your-personal-access-token-here"
      }
    }
  }
}

For VS Code with MCP

Create or update .vscode/mcp.json in your workspace:

Option 1: Using npx (Recommended)

{
  "servers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "mcp-jira-server"],
      "env": {
        "JIRA_BASE_URL": "https://jira.domain.com",
        "JIRA_PAT": "your-personal-access-token-here"
      }
    }
  }
}

Option 2: Using source build

{
  "servers": {
    "jira": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-jira-server/build/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://jira.domain.com",
        "JIRA_PAT": "your-personal-access-token-here"
      }
    }
  }
}

Environment Variables

JIRA_BASE_URL: The base URL of your self-hosted Jira instance (e.g., https://jira.domain.com)
JIRA_PAT: Your Personal Access Token

Available Tools

1. `jira_get_issue`

Get details of a specific Jira issue by its key.

Parameters:

issueKey (string, required): The Jira issue key (e.g., "PROJ-123")

Example:

Get details for issue PROJ-123

2. `jira_search_issues`

Search for Jira issues using JQL (Jira Query Language).

Parameters:

jql (string, required): JQL query string
maxResults (number, optional): Maximum number of results (default: 50)

Example:

Search for all open issues in project PROJ assigned to me

Common JQL Examples:

project = PROJ AND status = Open
assignee = currentUser() AND status != Done
priority = High AND created >= -7d
reporter = john.doe AND status IN (Open, "In Progress")

3. `jira_create_issue`

Create a new Jira issue.

Parameters:

projectKey (string, required): Project key
summary (string, required): Issue title/summary
issueType (string, required): Issue type (e.g., "Bug", "Task", "Story")
description (string, optional): Detailed description
priority (string, optional): Priority level (e.g., "High", "Medium", "Low")
assignee (string, optional): Username to assign to
labels (array, optional): Array of labels
components (array, optional): Array of component names

Example:

Create a new bug in project PROJ with summary "Login page not loading" and high priority

4. `jira_update_issue`

Update an existing Jira issue.

Parameters:

issueKey (string, required): Issue key to update
summary (string, optional): New summary
description (string, optional): New description
assignee (string, optional): New assignee username
priority (string, optional): New priority
labels (array, optional): New labels array
status (string, optional): New status (e.g., "In Progress", "Done")

Example:

Update issue PROJ-123 to set status to "In Progress" and assign to john.doe

5. `jira_add_comment`

Add a comment to a Jira issue.

Parameters:

issueKey (string, required): Issue key
comment (string, required): Comment text

Example:

Add a comment to PROJ-123 saying "Fixed in latest deployment"

6. `jira_get_comments`

Get all comments from a Jira issue.

Parameters:

issueKey (string, required): Issue key

7. `jira_get_projects`

List all available Jira projects.

Parameters: None

Example:

List all Jira projects

8. `jira_get_project`

Get details of a specific project.

Parameters:

projectKey (string, required): Project key

9. `jira_get_issue_types`

Get available issue types for a project.

Parameters:

projectKey (string, required): Project key

10. `jira_assign_issue`

Assign a Jira issue to a user.

Parameters:

issueKey (string, required): Issue key
assignee (string, required): Username to assign to

11. `jira_delete_issue`

Delete a Jira issue permanently.

Parameters:

issueKey (string, required): Issue key to delete

⚠️ Warning: This action is permanent and cannot be undone.

12. `jira_get_current_user`

Get information about the currently authenticated user.

Parameters: None

Development

Build the server

npm run build

Watch mode for development

npm run watch

Run in development mode

npm run dev

Testing the Server

After configuring the server, restart Claude Desktop or VS Code to load the new MCP server.

Quick Test Commands

Test authentication:
```
Get my current Jira user information
```
List projects:
```
Show me all Jira projects
```

Search for issues:

Search for all issues assigned to me that are not done

Create an issue:

Create a new task in project PROJ with summary "Test MCP integration"

Troubleshooting

Server not connecting

Verify the absolute path in your configuration
Ensure the server is built (npm run build)
Check that environment variables are set correctly
Restart Claude Desktop or VS Code after configuration changes

Authentication errors

Verify your Personal Access Token is still valid
Check that the token has not expired
Ensure the token has appropriate permissions
Verify the JIRA_BASE_URL is correct (no trailing slash)

API errors

Check Jira server logs for detailed error messages
Verify the Jira API is accessible from your machine
Ensure your user account has necessary permissions
Try accessing the REST API directly: https://jira.domain.com/rest/api/2/myself

Common issues

"Cannot find module": Run npm install and npm run build
"Connection refused": Check if Jira server is accessible and URL is correct
"Unauthorized": Verify your Personal Access Token
"Issue type not found": Use jira_get_issue_types to see valid types for the project

Security Best Practices

Never commit your Personal Access Token to version control
Store tokens securely in configuration files with restricted permissions
Use tokens with minimal required permissions
Set expiration dates for tokens
Rotate tokens regularly
Monitor token usage in Jira's audit logs

API Reference

This MCP server uses the Jira REST API v2. For more information about Jira's API:

Jira REST API documentation: https://your-jira-instance/rest/api/2/
JQL syntax guide: Check your Jira instance documentation

License

MIT

Support

For issues related to:

MCP Server: Check the logs in Claude Desktop or VS Code
Jira API: Refer to your self-hosted Jira documentation
Authentication: Contact your Jira administrator

Contributing

Contributions are welcome! Please ensure:

Code follows TypeScript best practices
All tools are properly documented
Error handling is comprehensive
Security best practices are followed

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
src		src
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CONNECTION_TEST_RESULTS.md		CONNECTION_TEST_RESULTS.md
LICENSE		LICENSE
PROJECT_SUMMARY.md		PROJECT_SUMMARY.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
RELEASE_NOTES.md		RELEASE_NOTES.md
RELEASE_SUMMARY.md		RELEASE_SUMMARY.md
claude_desktop_config.example.json		claude_desktop_config.example.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vscode_mcp_config.example.json		vscode_mcp_config.example.json

Uh oh!

License

Uh oh!

edrich13/mcp-jira-server

Folders and files

Latest commit

History

Repository files navigation

MCP Jira Server for Self-Hosted Jira

Features

Prerequisites

How to Create a Personal Access Token in Self-Hosted Jira

Installation

Option 1: Using npm (Recommended)

Option 2: From Source

Configuration

For Claude Desktop

For VS Code with MCP

Environment Variables

Available Tools

1. jira_get_issue

2. jira_search_issues

3. jira_create_issue

4. jira_update_issue

5. jira_add_comment

6. jira_get_comments

7. jira_get_projects

8. jira_get_project

9. jira_get_issue_types

10. jira_assign_issue

11. jira_delete_issue

12. jira_get_current_user

Development

Build the server

Watch mode for development

Run in development mode

Testing the Server

Quick Test Commands

Troubleshooting

Server not connecting

Authentication errors

API errors

Common issues

Security Best Practices

API Reference

License

Support

Contributing

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Languages

1. `jira_get_issue`

2. `jira_search_issues`

3. `jira_create_issue`

4. `jira_update_issue`

5. `jira_add_comment`

6. `jira_get_comments`

7. `jira_get_projects`

8. `jira_get_project`

9. `jira_get_issue_types`

10. `jira_assign_issue`

11. `jira_delete_issue`

12. `jira_get_current_user`

Packages