Skip to main content
Glama

MCP Jira Server

TypeScript Node License: MIT npm version MCP Server

CI codecov GitHub issues

A Model Context Protocol (MCP) server for Jira API integration. Enables reading, writing, and managing Jira issues and projects directly from your MCP client (e.g., Claude Desktop).

⚡ Quick Install for Claude Code

The fastest way to add this MCP server to Claude Code:

claude mcp add jira npx mcp-jira-stdio@latest \
  --env JIRA_BASE_URL=https://yourcompany.atlassian.net \
  --env JIRA_EMAIL=your-email@example.com \
  --env JIRA_API_TOKEN=your-api-token

Replace the values with your actual Jira credentials:

  • JIRA_BASE_URL: Your Jira instance URL (e.g., https://yourcompany.atlassian.net)

  • JIRA_EMAIL: Your Jira account email

  • JIRA_API_TOKEN: Your Jira API token (generate here)

That's it! The server will be automatically configured and ready to use.

Alternative: Manual Configuration

If you prefer to configure manually or use Claude Desktop, see the Configuration section below.

Related MCP server: JIRA MCP Tools

🚀 Quick Start

1. Prerequisites

  • Node.js v20 or higher

  • Jira instance (Cloud or Server)

  • Jira API token

2. Installation

# Install from npm
npm install -g mcp-jira-stdio

# Or install locally in your project
npm install mcp-jira-stdio

Development Installation

# Clone the repository
git clone https://github.com/freema/mcp-jira-stdio.git
cd mcp-jira-stdio

# Install dependencies
npm install
# or using Task runner
task install

# Build the project
npm run build
# or
task build

3. Jira API Setup

  1. Go to your Jira instance settings

  2. Create an API token:

    • Jira Cloud: Go to Account Settings → Security → Create and manage API tokens

    • Jira Server: Use your username and password (or create an application password)

  3. Note your Jira base URL (e.g., https://yourcompany.atlassian.net)

4. Configuration

Create a .env file from the provided example:

# Copy the example environment file
cp .env.example .env

# Edit .env with your actual Jira credentials
# Or use Task runner:
task env

Example .env contents:

JIRA_BASE_URL=https://your-instance.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_API_TOKEN=your-api-token

Note: Generate your API token at https://id.atlassian.com/manage-profile/security/api-tokens

5. Test Connection

# Test Jira connection
task jira:test

# List visible projects
task jira:projects

6. Configure MCP Client

For Claude Code

Use the quick install command (recommended):

claude mcp add jira npx mcp-jira-stdio@latest \
  --env JIRA_BASE_URL=https://yourcompany.atlassian.net \
  --env JIRA_EMAIL=your-email@example.com \
  --env JIRA_API_TOKEN=your-api-token

For Claude Desktop

Add to your Claude Desktop config:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "jira": {
      "command": "mcp-jira-stdio",
      "env": {
        "JIRA_BASE_URL": "https://your-instance.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Alternative: Using npx

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["mcp-jira-stdio"],
      "env": {
        "JIRA_BASE_URL": "https://your-instance.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Restart Claude Desktop after adding the configuration.

📦 Available Tools

Projects

  • jira_get_visible_projects: Retrieves all projects visible to the user.

  • jira_get_project_info: Retrieves detailed information about a project (components, versions, roles, insights).

Issues

  • jira_get_issue: Retrieve issue details by key (supports optional fields/expand).

  • jira_search_issues: Search for Jira issues using JQL with pagination and fields.

  • jira_create_issue: Create a new issue in a project (type, priority, assignee, labels, components).

  • jira_update_issue: Update an existing issue (summary, description, priority, assignee, labels, components, fix versions).

  • jira_create_subtask: Create a subtask under a parent issue (auto-detects subtask type).

Comments

  • jira_add_comment: Add a comment to an issue (optional visibility by group/role).

Metadata & Users

  • jira_get_create_meta: Get create metadata for a project showing all available fields (including custom fields) with their allowed values. Essential for discovering required fields before creating issues.

  • jira_get_issue_types: List issue types (optionally per project).

  • jira_get_users: Search for users (by query, username, or accountId).

  • jira_get_priorities: List available priorities.

  • jira_get_statuses: List available statuses (global or project-specific).

  • jira_get_custom_fields: List all custom fields in Jira with their types and schemas.

My Work

  • jira_get_my_issues: Retrieve issues assigned to the current user (sorted by updated).

🛠️ Development

Development Commands

# Development mode with hot reload
npm run dev
task dev

# Build for production
npm run build
task build

# Type checking
npm run typecheck
task typecheck

# Linting
npm run lint
task lint

# Format code
npm run format
task fmt

# Run all checks
npm run check
task check

MCP Inspector

Debug your MCP server using the inspector:

# Run inspector (production build)
npm run inspector
task inspector

# Run inspector (development mode)
npm run inspector:dev
task inspector:dev

Notes:

  • Startup no longer blocks on Jira connectivity. If Jira env vars are missing, the server still starts and lists tools; tool calls will fail with a clear auth error until you set JIRA_BASE_URL, JIRA_EMAIL, and JIRA_API_TOKEN.

  • Connection testing runs only in development/test (NODE_ENV=development or test). Failures are logged but do not terminate the server, so the inspector can still display tools.

Testing

# Run tests
npm test
task test

# Run tests with coverage
npm run test:coverage
task test:coverage

# Watch mode
npm run test:watch
task test:watch

📋 Project Structure

src/
├── index.ts              # Entry point & MCP server setup
├── config/
│   └── constants.ts      # API configuration & constants
├── tools/
│   ├── index.ts          # Tool exports
│   └── get-visible-projects.ts  # Get visible projects tool
├── types/
│   ├── common.ts         # Common types & interfaces
│   ├── jira.ts           # Jira API types
│   └── tools.ts          # Tool input/output schemas
└── utils/
    ├── jira-auth.ts      # Jira authentication & client
    ├── validators.ts     # Input validation with Zod
    ├── formatters.ts     # Response formatting
    ├── error-handler.ts  # Error handling
    └── api-helpers.ts    # Jira API helpers

🔧 Tool Usage Examples

Get Visible Projects

// List all projects
jira_get_visible_projects({});

// List projects with additional details
jira_get_visible_projects({
  expand: ['description', 'lead', 'issueTypes'],
});

// List recent projects only
jira_get_visible_projects({
  recent: 10,
});

❗ Troubleshooting

Common Issues

"Authentication failed"

  • Verify your API token is correct

  • Check that your email matches your Jira account

  • Ensure your Jira base URL is correct (no trailing slash)

"Connection failed"

  • Verify your Jira instance is accessible

  • Check network connectivity

  • Ensure Jira REST API is enabled

"Permission denied"

  • Verify your account has the necessary permissions

  • Check project permissions in Jira

  • Ensure you're using the correct Jira instance

MCP Connection Issues

  • Ensure you're using the built version (dist/index.js)

  • Check that Node.js path is correct in Claude Desktop config

  • Look for errors in Claude Desktop logs

  • Use task inspector to debug

Timeout when running multiple instances with npx

If you're running multiple Claude Code sessions simultaneously and experience timeouts, this is caused by npx cache/registry locking — not the MCP server itself. Each instance tries to verify the package, causing conflicts. To fix this, install the package globally instead:

npm install -g mcp-jira-stdio
claude mcp add jira mcp-jira-stdio \
  --env JIRA_BASE_URL=... \
  --env JIRA_EMAIL=... \
  --env JIRA_API_TOKEN=...

Debug Commands

# Test Jira connection
task jira:test

# List projects (test API connectivity)
task jira:projects

# Run MCP inspector for debugging
task inspector:dev

# Check all configuration
task check

If the inspector shows an SSE error and the server exits immediately, ensure you are not forcing an early exit with invalid credentials. With the current behavior, the server should not exit on missing credentials; export your Jira vars to exercise the tools:

export JIRA_BASE_URL="https://your-instance.atlassian.net"
export JIRA_EMAIL="your-email@example.com"
export JIRA_API_TOKEN="your-api-token"
npm run inspector

🔍 Environment Variables

Variable

Required

Description

Example

JIRA_BASE_URL

Yes

Jira instance URL

https://company.atlassian.net

JIRA_EMAIL

Yes

Your Jira email

user@example.com

JIRA_API_TOKEN

Yes

Jira API token

ATxxx...

NODE_ENV

No

Environment mode

development or production

🤝 Contributing

  1. Fork the repository

  2. Create your feature branch (git checkout -b feature/amazing-feature)

  3. Run tests and linting (task check)

  4. Commit your changes (git commit -m 'Add some amazing feature')

  5. Push to the branch (git push origin feature/amazing-feature)

  6. Open a Pull Request

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

MCP Config Setup

Configure Claude Desktop to use this MCP server interactively:

npm run setup:mcp

The script will:

  • Build the project if needed and detect your Node path

  • Prompt for JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN

  • Save a jira entry into your Claude Desktop config or print the JSON

  • Optionally generate a local .env for development

Available Tools

23 tools
jira_add_attachmentA

Uploads an attachment (image, document, etc.) to a Jira issue.

EFFICIENT METHOD (recommended for large files):

  • fileUrl: Provide URL to remote file - MINIMAL tokens (~60 tokens) Example: Upload to Dropbox/S3/imgur first, then provide URL

DIRECT METHOD (for small files):

  • content: Base64 encoded content - WARNING: HIGH token cost (~330,000 tokens for 1MB file) Only suitable for small files (< 500 KB)

Returns attachment metadata including ID and download URL. To reference the image in a comment or description, use wiki markup: !filename.png! or !filename.png|thumbnail!

Inputs: filename (required), issueKey (required), content, fileUrl, +1 more.

jira_add_commentA

Adds a comment to an issue. Supports visibility restrictions for groups or roles. Comment format is controlled by the "format" parameter (default: markdown). Returns the created comment with author details and timestamp.

Inputs: body (required), issueKey (required), format, visibility.

jira_create_issueA

Creates a new Jira issue in the specified project. Supports setting issue type, priority, assignee, labels, components, and custom fields. Description format is controlled by the "format" parameter (default: markdown). For required custom fields, supply them via customFields (e.g., { "customfield_12345": { id: "..." } }). Returns the created issue with all details.

Inputs: summary (required), issueType (required), projectKey (required), format, +7 more.

jira_create_subtaskA

Creates a subtask under an existing parent issue. Automatically determines the correct project and subtask issue type. Supports setting priority, assignee, labels, and components. Description format is controlled by the "format" parameter (default: markdown).

Inputs: summary (required), parentIssueKey (required), format, labels, +4 more.

jira_delete_attachmentA
Destructive

Deletes an attachment from Jira by its attachment ID. Use jira_get_attachments to find attachment IDs.

Inputs: attachmentId (required).

jira_get_attachmentsA
Read-only

Lists all attachments on a Jira issue. Returns attachment metadata including filename, size, MIME type, author, and download URL.

Inputs: issueKey (required).

jira_get_commentsA
Read-only

Retrieves all comments for a Jira issue. Returns comment author, content, timestamps, and visibility settings. Supports pagination for issues with many comments.

Inputs: issueKey (required), orderBy, startAt, maxResults.

jira_get_create_metaA
Read-only

Retrieves create metadata for a project, showing all available fields (including custom fields) for creating issues. Shows required vs optional fields, field types, and allowed values. Use this before creating issues to discover what fields are needed.

Inputs: projectKey (required), issueTypeName.

jira_get_custom_fieldsA
Read-only

Retrieves all custom fields available in Jira. Shows custom field names, IDs (e.g., customfield_10071), and types. Useful for discovering what custom fields exist and their identifiers.

Inputs: projectKey.

jira_get_issueA
Read-only

Retrieve details for a specific Jira issue by key or URL. Use this when the user mentions an issue like "PAYWALL-943" or pastes a Jira link (e.g., https://your.atlassian.net/browse/PAYWALL-943). Returns status, assignee, priority, project, type, labels, components, timestamps, and description.

Inputs: issueKey (required), expand, fields.

jira_get_issue_graphA
Read-only

Build a dependency/relationship graph starting from a seed issue. Returns a map of connected issues (parent/child hierarchy, blocks, relates to, duplicates, etc.) with nodes and edges, plus a Mermaid diagram for visualization. Use this to understand how issues are connected across epics, stories, and subtasks.

Inputs: issueKey (required), maxDepth, maxNodes, direction, +2 more.

jira_get_issue_typesA
Read-only

Retrieves available issue types. Can get global issue types or project-specific issue types including regular issues and subtasks (Bug, Story, Task, Epic, etc.).

Inputs: projectKey.

jira_get_my_issuesA
Read-only

Retrieves issues assigned to current user, sorted by most recently updated first. Supports pagination and field selection. For pagination, use nextPageToken from previous response.

Inputs: expand, fields, maxResults, nextPageToken.

jira_get_prioritiesA
Read-only

Retrieves available priorities (e.g., Highest, High, Medium, Low, Lowest). Returns IDs, names, and descriptions.

Inputs: no named parameters.

jira_get_project_infoA
Read-only

Retrieves detailed information about a project (components, versions, issue types, roles, insights). More comprehensive than the basic project list.

Inputs: projectKey (required), expand.

jira_get_statusesA
Read-only

Retrieves available statuses (global or project-specific, e.g., To Do, In Progress, Done). Returns status categories and workflow information.

Inputs: projectKey, issueTypeId.

jira_get_transitionsA
Read-only

Retrieves all available workflow transitions for a Jira issue. Use this to discover which status changes are possible for an issue before calling jira_transition_issue.

Inputs: issueKey (required).

jira_get_usersA
Read-only

Search for users by name, email, username, or account ID. Returns display name, email, account status, and account type. Supports pagination.

Inputs: query, startAt, username, accountId, +1 more.

jira_get_visible_projectsB
Read-only

Retrieves all projects accessible to the authenticated user. Returns project keys, names, descriptions, and basic metadata.

Inputs: expand, recent.

jira_search_issuesA
Read-only

Search for Jira issues using JQL. Supports complex queries with pagination and field selection. Examples: "project = PROJECT AND status = Open", "assignee = currentUser()". For pagination, use nextPageToken from previous response.

Inputs: jql (required), expand, fields, maxResults, +1 more.

jira_transition_issueA

Transitions a Jira issue to a new workflow status (e.g., "To Do" -> "In Progress" -> "Done"). Use jira_get_transitions first to discover available transitions. Supports adding a comment and setting resolution during the transition.

Inputs: issueKey (required), format, comment, resolution, +2 more.

jira_update_issueA

Updates an existing Jira issue by its key. Supports updating summary, description, priority, assignee, labels, components, and fix versions. Description format is controlled by the "format" parameter (default: markdown). Only specified fields will be updated.

Inputs: issueKey (required), format, labels, parent, +7 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 23 tools

    Disambiguation4/5

    Most tools target distinct resources and actions, and descriptions clarify boundaries (e.g., get_visible_projects vs get_project_info). However, minor overlaps exist: jira_get_my_issues could be achieved via jira_search_issues with assignee=currentUser(), and jira_get_issue_types vs jira_get_create_meta both relate to issue type discovery for creation.

    Naming Consistency5/5

    All tools follow a consistent jira_<verb>_<noun> snake_case pattern, with clear verbs like get, create, update, add, delete, search, and transition. Minor variations like get_visible_projects and get_my_issues remain predictable and readable.

    Tool Count3/5

    With 23 tools, the set is on the heavy side for a single MCP server, though Jira's complexity justifies many of them. The count falls into the borderline-heavy range (16-25) where consolidation or grouping could improve usability.

    Completeness4/5

    The surface covers core Jira issue lifecycle: create, read, update, search, comment, attach, link, subtask, transition, and relationship graphing. Gaps remain, such as no jira_delete_issue, no update/delete for comments, and no worklog operations, but these are minor and agents can often work around them.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server that enables interaction with JIRA APIs through Claude Desktop, allowing users to search, create, update, and manage JIRA issues using natural language commands.
      1
      -
    • A
      license
      A
      quality
      F
      maintenance
      A Model Context Protocol server that enables interaction with Jira's REST API using natural language commands, allowing users to manage Jira projects, issues, comments, and workflows through Claude Desktop and other MCP clients.
      10
      7
      MIT