Jira MCP Server

Jira MCP Server

A modular, extensible Model Context Protocol (MCP) server for interacting with Jira Cloud. This project provides a set of tools to query boards, issues, user information, and more, making it easy to integrate Jira with AI agents, bots, or other automation systems.

🚀 Features

• List all available Jira scrum boards
• List your own issues for a specific board
• Add comments to Jira issues (ADF-compliant)
• Get current authenticated user information
• Search for users by login, email, or display name
• Get Jira server information (including server time)
• Modular, extensible, and easy to contribute

🛠️ Requirements

• Node.js 18+
• Access to a Jira Cloud instance
• Jira API Token (see Jira API Tokens)

⚙️ Environment Variables

Set the following environment variables in your shell or .env file:

JIRA_BASE_URL=https://your-domain.atlassian.net
JIRA_EMAIL=your-email@company.com
JIRA_API_TOKEN=your-jira-api-token

🚀 Quick Start (with npx)

You can run the Jira MCP Server instantly with npx, no global install required:

npx -y @ahmetbarut/jira-mcp-server

Or, if you want to use it as an MCP tool in a config file (e.g. mcp.json):

{
  "Jira MCP Server": {
    "command": "npx",
    "args": ["-y", "@ahmetbarut/jira-mcp-server"],
    "env": {
      "JIRA_BASE_URL": "https://your-domain.atlassian.net",
      "JIRA_EMAIL": "your-email@company.com",
      "JIRA_API_TOKEN": "your-jira-api-token"
    }
  }
}

• No need for npm install or global install.
• All dependencies are handled by npx.
• You can set your Jira credentials in the env section.

Note: The first run may take a few seconds as npx downloads the package.

📦 Installation & Setup

1. Clone the repository (optional):

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

2. Install globally (optional):

    npm install -g @ahmetbarut/jira-mcp-server

3. Set environment variables:
   • See above for required variables.
4. Build the project (if using from source):

    npm run build

5. Run the server:

    jira-mcp-server
    # or
    npx -y @ahmetbarut/jira-mcp-server

🧩 Usage

This server is designed to be used as an MCP tool server, typically via stdio. You can interact with it using the Model Context Protocol Inspector or integrate it into your own MCP-compatible agent.

Example: List Boards

npx @modelcontextprotocol/inspector --cli npx -y @ahmetbarut/jira-mcp-server --method tools/call --tool-name get_boards

Example: Get Your Issues for a Board

npx @modelcontextprotocol/inspector --cli npx -y @ahmetbarut/jira-mcp-server --method tools/call --tool-name get_issues --tool-arg boardId=123

Example: Add a Comment to an Issue

npx @modelcontextprotocol/inspector --cli npx -y @ahmetbarut/jira-mcp-server --method tools/call --tool-name add_comment_to_issue --tool-arg issueIdOrKey=PROJ-123 --tool-arg body="This is a test comment."

🧰 Available Tools

• get_boards: List all available Jira scrum boards
• get_issues: List your issues for a specific board
• add_comment_to_issue: Add a comment to a Jira issue (ADF-compliant)
• get_current_user_info: Get current authenticated user information
• search_user: Search for a user by login, email, or display name
• get_server_info: Get Jira server information (including server time)

🏗️ Project Structure

• src/index.ts — Main server entry point and tool dispatcher
• src/tools.ts — Tool definitions and schemas
• src/handlers.ts — Tool handler implementations (business logic)
• src/jiraApi.ts — Jira API helpers and configuration
• src/types.ts — TypeScript types and interfaces

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a new branch for your feature or bugfix:

    git checkout -b my-feature

3. Write clear, well-documented code
4. Add or update tests if applicable
5. Open a pull request with a clear description of your changes
6. Ensure your code passes lint and build checks

Code Style

• Use TypeScript and follow the existing modular structure
• Keep business logic in handlers.ts and API helpers in jiraApi.ts
• Write clear commit messages

Issues

If you find a bug or have a feature request, please open an issue on GitHub with as much detail as possible.

📄 License

This project is licensed under the MIT License. See LICENSE for details.

Happy automating with Jira MCP Server!