Jira MCP Server

An MCP (Model Context Protocol) server for Jira integration. Connect your AI coding assistant to your Jira instance to search, create, update, and manage issues without leaving your editor.

Features

• 12 tools exposed via MCP stdio transport

• Auth via Jira API token (HTTP Basic)

• Search using the latest /rest/api/3/search/jql endpoint

• JSON Schema tool definitions (compatible with strict MCP clients)

Available Tools

Related MCP server: Jira Cloud MCP Server

Prerequisites

• Node.js 20+ (uses built-in fetch)

• A Jira Cloud account with an API token

• Your Jira site URL (e.g. https://your-team.atlassian.net)

Create a Jira API Token

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens

2. Click Create API token

3. Name it (e.g. "MCP Server")

4. Copy the token (starts with ATATT3)

Setup

1. Clone and install

git clone <your-repo-url> jira-mcp
cd jira-mcp
npm install

2. Build

npm run build

3. Verify it works

npm run inspector

This launches the MCP Inspector — a web UI for testing MCP tools directly. Or test from the command line:

npm start

You should see: Jira MCP server running on stdio.

Note: The inspector and npm start commands require env vars to be available. You can pass them inline:

JIRA_HOST=https://your-team.atlassian.net JIRA_EMAIL=you@example.com JIRA_API_TOKEN=ATATT3xF... npm start

Or create a .env file (see below).

Connect to your AI assistant

The server communicates over stdio. All clients use the same command:

node /absolute/path/to/jira-mcp/build/index.js

Replace /absolute/path/to/jira-mcp with the actual path to your cloned repo.

Opencode

Edit ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {
      "type": "local",
      "command": ["node", "/absolute/path/to/jira-mcp/build/index.js"],
      "enabled": true,
      "timeout": 30000,
      "environment": {
        "JIRA_HOST": "https://your-team.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "ATATT3xF..."
      }
    }
  }
}

Restart opencode. Verify with:

opencode mcp list

Claude Code

Edit ~/.claude/claude_desktop_config.json (Claude Desktop) or .claude/settings.json (Claude Code CLI):

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/absolute/path/to/jira-mcp/build/index.js"],
      "env": {
        "JIRA_HOST": "https://your-team.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "ATATT3xF..."
      }
    }
  }
}

Restart Claude. Tools appear as mcp__jira__get_issue, mcp__jira__create_issue, etc.

Codex CLI

Edit ~/.codex/config.toml:

[mcp_servers.jira]
command = "node"
args = ["/absolute/path/to/jira-mcp/build/index.js"]
cwd = "/absolute/path/to/jira-mcp"
enabled = true
startup_timeout_sec = 30

[mcp_servers.jira.env]
JIRA_HOST = "https://your-team.atlassian.net"
JIRA_EMAIL = "your-email@example.com"
JIRA_API_TOKEN = "ATATT3xF..."

Restart Codex.

Cursor

Edit ~/.cursor/mcp.json (or .cursor/mcp.json in your project root):

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/absolute/path/to/jira-mcp/build/index.js"],
      "env": {
        "JIRA_HOST": "https://your-team.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "ATATT3xF..."
      }
    }
  }
}

Restart Cursor.

VS Code (with Continue extension)

Edit ~/.continue/config.json and add under experimental.modelContextProtocolServers:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "node",
          "args": ["/absolute/path/to/jira-mcp/build/index.js"],
          "env": {
            "JIRA_HOST": "https://your-team.atlassian.net",
            "JIRA_EMAIL": "your-email@example.com",
            "JIRA_API_TOKEN": "ATATT3xF..."
          }
        }
      }
    ]
  }
}

Restart VS Code.

VS Code note: As of mid-2026, native MCP support in VS Code is evolving. The Continue extension provides the most stable MCP integration. Check the Continue docs for the latest config format if the above doesn't match your version.

Environment variables

The server needs three variables. You only need to provide them once — either in your client config (recommended) or in a .env file. You do not need both.

Option A — Client config (recommended)

Pass env vars directly in your client's MCP config via the environment / env block. This is shown in all the client examples above. No .env file needed.

Option B — .env file (alternative)

If you prefer not to put credentials in each client's config, create a .env file in the repo root:

cp .env.example .env

Edit .env:

JIRA_HOST=https://your-team.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_API_TOKEN=ATATT3xF...

The server loads .env via dotenv.config() at startup. If the client config also passes env vars, those take precedence.

Important:

• JIRA_HOST must be your Jira site URL (e.g. https://your-team.atlassian.net), not an Atlassian org admin URL.

• The API token authenticates via HTTP Basic (email + token), not Bearer. This is handled automatically by the server.

• .env is gitignored — never commit your token.

Variables

Usage examples

Once connected, ask your AI assistant in natural language:

• "Get issue KAN-42"

• "Create a task called 'Fix login bug' in project KAN, assign to sadeq@example.com"

• "Show me all In Progress issues with High priority"

• "List all Jira users"

• "Find the user with email alice@example.com"

• "Update KAN-15 status to In Progress"

• "Link KAN-3 and KAN-7 with 'Blocks'"

The AI will call the appropriate MCP tool automatically.

Development

# Watch mode (auto-rebuild on save)
npm run dev

# Typecheck only
npx tsc --noEmit

# Run inspector for interactive testing
npm run inspector

Tech stack

• Runtime: Node.js 20+

• MCP SDK: @modelcontextprotocol/sdk

• Jira client: jira.js (v3) — with a custom fetch workaround for the deprecated search endpoint

• Schema validation: zod + zod-to-json-schema for MCP-compatible JSON Schema output

• Language: TypeScript (ESM)

Known limitations

• The searchForIssuesUsingJql method in jira.js targets a deprecated Atlassian endpoint. We bypass it with a direct fetch to /rest/api/3/search/jql.

• create_issue and update_issue assign via accountId (not username) for Jira Cloud compatibility.

• No support yet for comments, worklogs, sprints, attachments, or watchers. See the open tasks in your Jira board for planned additions.

Troubleshooting

Security

• .env is gitignored — never commit your API token.

• If you store credentials in your client config (e.g. opencode.json, config.toml), ensure that file is also gitignored or stored outside version control.

• The Jira API token grants full access to your Jira account. Treat it like a password.