MCP 服务器

mcp-jira-stdio

MCP server for Jira integration with stdio transport. Enables reading, writing, and managing Jira issues and projects directly from Claude Desktop. Supports issue creation, updates, comments, JQL search, and project management.

README

MCP Jira Server

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 Start

1. Prerequisites

Node.js v18 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

Go to your Jira instance settings
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)
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

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).
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_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).

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

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

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

🔍 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

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Run tests and linting (task check)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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