Mcp Jira Stdio

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 [email protected] \  --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.

🚀 Quick Start

1. Prerequisites

• Node.js v20 or higher
• Jira instance (Cloud or Server)
• Jira API token

2. Installation

# Install from npmnpm install -g mcp-jira-stdio
# Or install locally in your projectnpm install mcp-jira-stdio

Development Installation

# Clone the repositorygit clone https://github.com/freema/mcp-jira-stdio.gitcd mcp-jira-stdio
# Install dependenciesnpm install# or using Task runnertask install
# Build the projectnpm run build# ortask 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 filecp .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[email protected]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 connectiontask jira:test
# List visible projectstask 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 [email protected] \  --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": "[email protected]",        "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": "[email protected]",        "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 reloadnpm run devtask dev
# Build for productionnpm run buildtask build
# Type checkingnpm run typechecktask typecheck
# Lintingnpm run linttask lint
# Format codenpm run formattask fmt
# Run all checksnpm run checktask check

MCP Inspector

Debug your MCP server using the inspector:

# Run inspector (production build)npm run inspectortask inspector
# Run inspector (development mode)npm run inspector:devtask 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 testsnpm testtask test
# Run tests with coveragenpm run test:coveragetask test:coverage
# Watch modenpm run test:watchtask 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 projectsjira_get_visible_projects({});
// List projects with additional detailsjira_get_visible_projects({  expand: ['description', 'lead', 'issueTypes'],});
// List recent projects onlyjira_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-stdioclaude mcp add jira mcp-jira-stdio \  --env JIRA_BASE_URL=... \  --env JIRA_EMAIL=... \  --env JIRA_API_TOKEN=...

Debug Commands

# Test Jira connectiontask jira:test
# List projects (test API connectivity)task jira:projects
# Run MCP inspector for debuggingtask inspector:dev
# Check all configurationtask 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="[email protected]"export JIRA_API_TOKEN="your-api-token"npm run inspector

🔍 Environment Variables

🤝 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