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

Tool	Description	Read/Write
get_issue	Get a single issue by key	Read
get_issues	Search issues by project, board, or raw JQL	Read
get_assigned_issues	Get issues assigned to a user	Read
create_issue	Create a new issue	Write
update_issue	Update issue fields (summary, description, assignee, status, priority)	Write
delete_issue	Delete an issue (destructive)	Write
create_issue_link	Link two issues (Blocks, Relates to, etc.)	Write
get_user	Find a user by email	Read
list_users	List all Jira users (paginated)	Read
list_fields	List all available Jira fields	Read
list_issue_types	List all issue types (Bug, Task, Story, Epic)	Read
list_link_types	List all issue link types	Read

---

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

Variable	Required	Example
JIRA_HOST	Yes	https://your-team.atlassian.net
JIRA_EMAIL	Yes	your-email@example.com
JIRA_API_TOKEN	Yes	ATATT3xF... (from Atlassian API token page)

---

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

Problem	Cause	Fix
JIRA_HOST, JIRA_EMAIL, and JIRA_API_TOKEN environment variables are required	Env vars not loaded	Pass them in client config environment/env block, or create .env in the repo root
server unavailable / failed to load in client	Bad JSON Schema in tools/list	Rebuild with npm run build and restart the client
The requested API has been removed	Old jira.js search endpoint	Already fixed — ensure you're on the latest build
assignee: null after create/update	Using legacy name instead of accountId	Already fixed — ensure you're on the latest build
Connection works but tools don't appear	Client not restarted after config change	Fully quit and restart the client (config is loaded once at startup)
JIRA_HOST is an org URL, not a site URL	Wrong host format	Use https://your-team.atlassian.net, not https://home.atlassian.com/o/...

---

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.