Jira MCP Server

MCP (Model Context Protocol) server for Jira Cloud API integration. Create issues and list issue types using Basic Auth (email + API token).

Features

• jira_create_issue – Create a new Jira issue with project, summary, and issue type
• jira_list_issue_types – List available issue types for a project

Prerequisites

• Node.js 24+
• Jira Cloud site
• Atlassian API token

Setup

1. Clone and install

   cd jira_mcp
   npm install
   

2. Configure environment

   Copy .env.example to .env and fill in your values:

   cp .env.example .env
   

   JIRA_BASE_URL=https://your-domain.atlassian.net
   JIRA_EMAIL=user@example.com
   JIRA_API_TOKEN=your_api_token_here
   

3. Build

   npm run build
   

Usage

Run the server

npm start

Or with env vars inline:

JIRA_BASE_URL=https://your-domain.atlassian.net JIRA_EMAIL=you@example.com JIRA_API_TOKEN=xxx npm start

The server runs via stdio and is intended to be used as a subprocess by MCP clients (e.g. Cursor, Claude Desktop).

Cursor configuration

Add to your Cursor MCP config (e.g. ~/.cursor/mcp.json):

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/path/to/jira_mcp/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Tools

jira_list_issue_types

List issue types (Bug, Task, Story, etc.) for a project.

Parameter	Type	Required	Description
project_key	string	Yes	Jira project key (e.g. PROJ)
response_format	string	No	markdown (default) or json

jira_create_issue

Create a new Jira issue.

Parameter	Type	Required	Description
project_key	string	Yes	Jira project key
summary	string	Yes	Issue title
issue_type	string	Yes	Issue type name (e.g. Bug, Task) or ID
description	string	No	Issue description
response_format	string	No	markdown (default) or json

Testing Without Cursor

The best way to test the MCP server interactively is with MCP Inspector, a web UI for exercising tools, resources, and prompts.

1. Build the project (if not already done):

   npm run build
   

2. Run MCP Inspector with your server. With a .env file in the project root, the server loads it automatically:

   npm run inspector
   

   Or run directly (env from .env is loaded by the server):

   npx @modelcontextprotocol/inspector node dist/index.js
   

   To pass env vars explicitly instead:

   npx @modelcontextprotocol/inspector \
     -e JIRA_BASE_URL=https://your-domain.atlassian.net \
     -e JIRA_EMAIL=you@example.com \
     -e JIRA_API_TOKEN=your-token \
     node dist/index.js
   

3. Open the Inspector in your browser (typically http://localhost:6274).

4. Test tools – Use the Tools tab to call jira_list_issue_types and jira_create_issue with sample inputs.

The Inspector runs your server as a subprocess and connects via stdio, so it behaves like a real MCP client.

Development

# Run with auto-reload
npm run dev

# Run all tests (unit + integration)
npm test

# Run tests with coverage
npm run test:coverage

# Run integration tests only (spawns MCP server + mock Jira)
npm run test:integration

# Lint code
npm run lint
npm run lint:fix

# Format code
npm run format
npm run format:check

Pre-commit hooks (Husky)

On each git commit, Husky runs lint and Prettier on staged files. If there are errors, the commit is blocked with a message:

❌ Commit blocked: Fix the lint or Prettier errors above.
   Tips: npm run lint:fix  |  npm run format

To bypass (use sparingly): git commit --no-verify or HUSKY=0 git commit

CI

GitHub Actions runs on pull requests to main/master with separate stages on Node.js 24.x:

• Unit Tests – npm run test:unit (90% coverage enforced)
• Integration Tests – npm run test:integration (MCP server + mock Jira)
• Lint & Format – ESLint and Prettier checks
• Security Audit – npm audit (fails on moderate+ vulnerabilities)
• CodeQL – Static security analysis (JavaScript/TypeScript)
• Dependency Review – Checks for vulnerable deps in PRs

Dependabot is configured for weekly dependency updates (.github/dependabot.yml).

To block merges until PRs pass, enable branch protection in GitHub: Settings → Branches → Add rule → Require status checks to pass before merging.

API Reference

• Jira REST API v3
• Basic Auth for REST APIs

License

MIT