jira-mcp

Jira Cloud MCP server built from the skeleton architecture, with Jira-first tools and full REST coverage through a generic Jira API request tool.

What this solution provides

• Jira-focused MCP tools for common workflows:

  • profile lookup (jira_get_myself)

  • project discovery (jira_list_projects, jira_get_project)

  • issue search and retrieval (jira_search_issues, jira_get_issue)

  • issue mutation (jira_create_issue, jira_edit_issue, jira_transition_issue, jira_add_comment)

• Full Jira REST v3 coverage via:

  • jira_api_request (generic method/path/query/body)

  • jira_operation_request (operation-key based request for documented high-value endpoints)

• Workflow and schema discovery helper:

  • jira_query_suggestion_schema_discovery (task-based tool recommendations with per-tool input schema and examples)

• Existing hardened HTTP transport and auth controls from the skeleton:

  • bearer token gate on /mcp

  • request limits and rate limits

  • IP/origin allow-lists

  • optional Vault-backed token verification path

Related MCP server: MCP Atlassian Node Server

Jira API sources used

• Jira docs landing page: https://confluence.atlassian.com/jira

• Jira Cloud REST API v3 intro: https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/

• Jira Cloud REST API groups (issues/projects/search/users), plus operation references from Atlassian documentation.

Architecture

• src/index.js: stdio MCP entrypoint

• src/http/index.js: HTTP MCP entrypoint

• src/http/server.js: streamable HTTP transport with auth/rate-limit/access logs

• src/mcp/server.js: Jira tool registration and auth wrapper

• src/services/targetService.js: Jira service client (JiraServiceClient) and operation catalog

• src/config/env.js: environment parsing and validation

Tool catalog

Shared behavior for all tools

• Transport and credentials selection:

  • All Jira calls use environment-backed client settings: JIRA_BASE_URL, JIRA_AUTH_MODE, auth credentials, JIRA_TIMEOUT_MS, and JIRA_API_PREFIX.

  • jira_scope_info and jira_connection_info expose app/user scope metadata derived from APP_NAME and MCP_CONFIG_DEFAULT_USER_ID.

• Mutating authorization gate:

  • If MCP_ADMIN_AUTH_KEY is set, mutating operations require a matching authorizationKey argument.

• Response envelope (all tools):

  • Success shape:

    {
      "content": [{ "type": "text", "text": "{\"ok\":true,\"status\":200,\"data\":{...}}" }]
    }

  • Error shape:

    {
      "content": [{ "type": "text", "text": "{\"ok\":false,\"status\":<code>,\"error\":\"message\"}" }],
      "isError": true
    }

• Common failure conditions:

  • Jira authentication failures (401/403).

  • Missing or invalid required parameters (schema validation or path params).

  • Jira endpoint not found (404) or unsupported operation key (400).

  • Request timeout at JIRA_TIMEOUT_MS.

Read-only tools

jira_connection_info

• Use when: verifying MCP/Jira runtime wiring and auth-mode configuration before any Jira operation.

• Do not use when: you need Jira data payloads (issues/projects) rather than configuration metadata.

• Risk class: read-only, low risk.

• Permissions and prerequisites: no Jira mutation permission needed; Jira credentials may be absent.

• Environment selection behavior: returns server identity, adminAuthConfigured, scope model, and Jira client config from env.

• Parameters: none.

• Expected data shape:

  • server: { name, version, adminAuthConfigured, scopeModel }

  • jira: { baseUrl, apiPrefix, timeoutMs, authMode, bearerTokenConfigured, basicUsernameConfigured, basicPasswordConfigured }

• Recommended tools:

  • Prerequisite: none.

  • Follow-up: jira_health_check, jira_get_myself.

• Example:

  { "name": "jira_connection_info", "arguments": {} }

jira_scope_info

• Use when: resolving app/user scoping for Vault token index and Postgres config rows.

• Do not use when: you only need Jira API objects.

• Risk class: read-only, low risk.

• Permissions and prerequisites: no Jira permission required.

• Environment selection behavior: uses APP_NAME and supplied userId or MCP_CONFIG_DEFAULT_USER_ID.

• Parameters:

  • userId?: non-empty string.

• Expected data shape:

  • { appName, userId, userIdPathSegment, postgres: {...}, vault: {...} }

• Common failures:

  • Invalid empty userId.

• Recommended tools:

  • Prerequisite: none.

  • Follow-up: jira_connection_info.

• Example:

  { "name": "jira_scope_info", "arguments": { "userId": "alice" } }

jira_list_operations

• Use when: discovering supported operation keys for jira_operation_request.

• Do not use when: you already know exact path/method and prefer jira_api_request.

• Risk class: read-only, low risk.

• Permissions and prerequisites: no mutation permission required.

• Environment selection behavior: independent of Jira auth success; lists locally registered catalog.

• Parameters:

  • group?: non-empty string; exact group match (case-insensitive).

  • method?: non-empty string; normalized to uppercase.

  • keyContains?: non-empty substring match.

• Expected data shape:

  • { groups: string[], operations: [{ key, method, path, group, description }] }

• Recommended tools:

  • Prerequisite: jira_connection_info.

  • Follow-up: jira_operation_request.

• Example:

  {
    "name": "jira_list_operations",
    "arguments": { "group": "issues", "method": "get", "keyContains": "issue" }
  }

jira_query_suggestion_schema_discovery

• Use when: you want guidance on which MCP tools to call and in what sequence for a Jira task.

• Do not use when: you already know the exact tool and request shape you need.

• Risk class: read-only, low risk.

• Permissions and prerequisites: none.

• Environment selection behavior: returns recommendations and tool metadata; does not call Jira.

• Parameters:

  • task?: non-empty free-text task description.

  • includeSchemas?: boolean (default true).

  • includeExamples?: boolean (default true).

  • includeMutating?: boolean (default true) to include write-capable tools.

• Expected data shape:

  • recommendations: ordered tool sequences with intent-specific reasoning.

  • tools: per-tool metadata, mutability, schema hints, and examples.

  • notes.mutatingAuthorization: admin-key behavior summary for mutating calls.

• Recommended tools:

  • Prerequisite: none.

  • Follow-up: suggested tool sequence from the response.

• Example:

  {
    "name": "jira_query_suggestion_schema_discovery",
    "arguments": {
      "task": "create issue and move it to done",
      "includeMutating": true
    }
  }

jira_health_check

• Use when: validating live Jira connectivity and credentials quickly.

• Do not use when: you need full profile details with specific field selection.

• Risk class: read-only, low risk.

• Permissions and prerequisites: requires Jira auth that can access /myself.

• Environment selection behavior: executes GET /myself through configured Jira client.

• Parameters: none.

• Expected data shape:

  • Jira HTTP response envelope: { method, path, url, status, contentType, data }.

• Common failures:

  • Invalid Jira base URL.

  • Token/user lacks access.

  • Timeout/network failures.

• Recommended tools:

  • Prerequisite: jira_connection_info.

  • Follow-up: jira_get_myself.

• Example:

  { "name": "jira_health_check", "arguments": {} }

jira_get_myself

• Use when: retrieving the current Jira principal profile.

• Do not use when: checking generic connectivity only (jira_health_check is lighter intent-wise).

• Risk class: read-only, low risk.

• Permissions and prerequisites: authenticated Jira identity with /myself access.

• Environment selection behavior: resolved through active env-based Jira auth mode.

• Parameters: none.

• Expected data shape:

  • Jira HTTP response envelope with profile payload in data.

• Recommended tools:

  • Prerequisite: jira_health_check.

  • Follow-up: jira_list_projects, jira_search_issues.

• Example:

  { "name": "jira_get_myself", "arguments": {} }

jira_list_projects

• Use when: searching/browsing projects with pagination.

• Do not use when: you already know one project key/id (jira_get_project).

• Risk class: read-only, low risk.

• Permissions and prerequisites: Jira project browse permission.

• Environment selection behavior: maps to GET /project/search with query params.

• Parameters:

  • startAt?: integer, >= 0.

  • maxResults?: integer, >= 1.

  • query?: string.

  • keys?: array of non-empty strings.

  • orderBy?: string.

• Expected data shape:

  • Jira HTTP response envelope with page payload (values, pagination metadata).

• Common failures:

  • Invalid numeric bounds.

  • Unauthorized project visibility.

• Recommended tools:

  • Prerequisite: jira_get_myself.

  • Follow-up: jira_get_project, jira_search_issues.

• Example:

  {
    "name": "jira_list_projects",
    "arguments": { "startAt": 0, "maxResults": 25, "query": "platform", "orderBy": "name" }
  }

jira_get_project

• Use when: retrieving one project by key or id.

• Do not use when: you need cross-project discovery (jira_list_projects).

• Risk class: read-only, low risk.

• Permissions and prerequisites: Jira access to target project.

• Environment selection behavior: calls GET /project/{projectIdOrKey}.

• Parameters:

  • projectIdOrKey: non-empty string (required).

  • expand?: string.

• Expected data shape:

  • Jira HTTP response envelope with project object.

• Common failures:

  • Missing projectIdOrKey.

  • Unknown project key/id (404).

• Recommended tools:

  • Prerequisite: jira_list_projects.

  • Follow-up: jira_search_issues.

• Example:

  { "name": "jira_get_project", "arguments": { "projectIdOrKey": "ENG" } }

jira_search_issues

• Use when: executing JQL search with field selection and pagination token support.

• Do not use when: retrieving a single known issue key (jira_get_issue).

• Risk class: read-only from business perspective, medium risk operationally (expensive queries).

• Permissions and prerequisites: Jira browse access for target projects/issues.

• Environment selection behavior: maps to POST /search/jql with body.

• Parameters:

  • jql: non-empty string (required).

  • maxResults?: integer, >= 1.

  • nextPageToken?: string.

  • fields?: array of non-empty strings.

  • expand?: array of non-empty strings.

  • reconcileIssues?: array of integers.

  • failFast?: boolean.

• Expected data shape:

  • Jira HTTP response envelope with search results (issues, paging metadata, optional token).

• Common failures:

  • Invalid JQL syntax.

  • Excessive payloads/permissions constraints.

• Recommended tools:

  • Prerequisite: jira_get_myself.

  • Follow-up: jira_get_issue, jira_transition_issue.

• Example:

  {
    "name": "jira_search_issues",
    "arguments": {
      "jql": "project = ENG ORDER BY updated DESC",
      "maxResults": 20,
      "fields": ["summary", "status", "assignee"]
    }
  }

jira_get_issue

• Use when: fetching one issue by key/id with optional field restriction.

• Do not use when: querying broad sets (jira_search_issues).

• Risk class: read-only, low risk.

• Permissions and prerequisites: Jira issue browse permission.

• Environment selection behavior: calls GET /issue/{issueIdOrKey}.

• Parameters:

  • issueIdOrKey: non-empty string (required).

  • fields?: array of non-empty strings.

  • expand?: string.

  • updateHistory?: boolean.

• Expected data shape:

  • Jira HTTP response envelope with issue object.

• Common failures:

  • Unknown issue key/id.

  • Field visibility restrictions.

• Recommended tools:

  • Prerequisite: jira_search_issues.

  • Follow-up: jira_edit_issue, jira_add_comment, jira_transition_issue.

• Example:

  {
    "name": "jira_get_issue",
    "arguments": { "issueIdOrKey": "ENG-123", "fields": ["summary", "status"] }
  }

Mutating tools

Safety warning: these operations can create or modify Jira data. Prefer calling read-only discovery tools first, validate issue/project identifiers, and use least-privilege credentials.

jira_create_issue

• Use when: creating a new issue with Jira field payload.

• Do not use when: unsure about required field schema for the issue type/project.

• Risk class: mutating, high risk.

• Permissions and prerequisites:

  • Jira create-issue permission in target project.

  • authorizationKey required when MCP_ADMIN_AUTH_KEY is configured.

• Environment selection behavior: calls POST /issue under configured JIRA_API_PREFIX.

• Parameters:

  • fields: object (required).

  • update?: object.

  • properties?: array.

  • transition?: object.

  • authorizationKey?: non-empty string.

• Expected data shape:

  • Jira HTTP response envelope with created issue identifiers.

• Common failures:

  • Missing required Jira fields.

  • Unauthorized mutation key.

• Recommended tools:

  • Prerequisite: jira_get_project, jira_list_operations.

  • Follow-up: jira_get_issue, jira_add_comment.

• Example:

  {
    "name": "jira_create_issue",
    "arguments": {
      "fields": {
        "project": { "key": "ENG" },
        "issuetype": { "name": "Task" },
        "summary": "Investigate webhook retry behavior"
      },
      "authorizationKey": "<admin-key-if-required>"
    }
  }

jira_edit_issue

• Use when: updating issue fields or applying Jira update operations.

• Do not use when: uncertain about field editability or transition requirements.

• Risk class: mutating, high risk.

• Permissions and prerequisites:

  • Jira edit-issue permission.

  • authorizationKey gate when configured.

• Environment selection behavior: calls PUT /issue/{issueIdOrKey}.

• Parameters:

  • issueIdOrKey: non-empty string (required).

  • body: object (required).

  • query?: object.

  • authorizationKey?: non-empty string.

• Expected data shape:

  • Jira HTTP response envelope (often 204/no content).

• Common failures:

  • Invalid field updates.

  • Unauthorized mutation key.

• Recommended tools:

  • Prerequisite: jira_get_issue.

  • Follow-up: jira_get_issue.

• Example:

  {
    "name": "jira_edit_issue",
    "arguments": {
      "issueIdOrKey": "ENG-123",
      "body": { "fields": { "summary": "Updated summary" } },
      "authorizationKey": "<admin-key-if-required>"
    }
  }

jira_transition_issue

• Use when: moving an issue to a new workflow state.

• Do not use when: transition id has not been validated for this issue.

• Risk class: mutating, high risk.

• Permissions and prerequisites:

  • Jira transition permission and valid transition id.

  • authorizationKey gate when configured.

• Environment selection behavior: calls POST /issue/{issueIdOrKey}/transitions.

• Parameters:

  • issueIdOrKey: non-empty string (required).

  • transitionId: positive integer or non-empty string (required).

  • fields?: object.

  • update?: object.

  • authorizationKey?: non-empty string.

• Expected data shape:

  • Jira HTTP response envelope (often 204/no content).

• Common failures:

  • Invalid transition id for current issue state.

  • Unauthorized mutation key.

• Recommended tools:

  • Prerequisite: jira_get_issue, jira_operation_request with transition-list operation.

  • Follow-up: jira_get_issue.

• Example:

  {
    "name": "jira_transition_issue",
    "arguments": {
      "issueIdOrKey": "ENG-123",
      "transitionId": "31",
      "authorizationKey": "<admin-key-if-required>"
    }
  }

jira_add_comment

• Use when: posting discussion/worklog context to an issue.

• Do not use when: you need structured field updates instead of comment text/body.

• Risk class: mutating, medium risk.

• Permissions and prerequisites:

  • Jira comment permission on target issue.

  • authorizationKey gate when configured.

• Environment selection behavior: calls POST /issue/{issueIdOrKey}/comment.

• Parameters:

  • issueIdOrKey: non-empty string (required).

  • body: any JSON value accepted by Jira comment API (required).

  • authorizationKey?: non-empty string.

• Expected data shape:

  • Jira HTTP response envelope with created comment data.

• Common failures:

  • Malformed comment body schema.

  • Unauthorized mutation key.

• Recommended tools:

  • Prerequisite: jira_get_issue.

  • Follow-up: jira_get_issue.

• Example:

  {
    "name": "jira_add_comment",
    "arguments": {
      "issueIdOrKey": "ENG-123",
      "body": {
        "type": "doc",
        "version": 1,
        "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "Investigating now." }] }]
      },
      "authorizationKey": "<admin-key-if-required>"
    }
  }

jira_operation_request

• Use when: executing a known, documented operation key from server catalog.

• Do not use when: operation key is unknown or you need arbitrary Jira endpoints (jira_api_request).

• Risk class: mixed; read-only or mutating depending on operation method.

• Permissions and prerequisites:

  • operationKey must exist in jira_list_operations output.

  • authorizationKey required if resolved method is mutating.

• Environment selection behavior:

  • Resolves path template params and executes against configured Jira client.

  • Uses operation-specific method/path from server catalog.

• Parameters:

  • operationKey: non-empty string (required).

  • pathParams?: object with primitive values (string|number|boolean).

  • query?: object with string|number|boolean|string[] values.

  • body?: any JSON value.

  • headers?: object of string headers.

  • authorizationKey?: non-empty string.

• Expected data shape:

  • Jira HTTP response envelope.

• Common failures:

  • Unknown operationKey (400).

  • Missing required path template value.

  • Unauthorized mutation key for mutating methods.

• Safety warnings:

  • Validate the method returned by jira_list_operations before executing.

  • Treat mutating keys (POST/PUT/PATCH/DELETE) as destructive.

• Recommended tools:

  • Prerequisite: jira_list_operations.

  • Follow-up: read tool matching affected resource (jira_get_issue, jira_get_project).

• Example:

  {
    "name": "jira_operation_request",
    "arguments": {
      "operationKey": "issueGet",
      "pathParams": { "issueIdOrKey": "ENG-123" }
    }
  }

jira_api_request

• Use when: you need full Jira REST coverage beyond first-class wrappers.

• Do not use when: a dedicated strongly-typed tool already exists (prefer safer wrappers first).

• Risk class: mixed; potentially high risk for mutating methods.

• Permissions and prerequisites:

  • Valid Jira endpoint path and schema knowledge required.

  • authorizationKey required when method is POST|PUT|PATCH|DELETE and admin key is configured.

• Environment selection behavior:

  • method normalized to uppercase.

  • path normalized to leading slash and resolved under JIRA_API_PREFIX unless already /rest/api/....

• Parameters:

  • method: non-empty string (required).

  • path: non-empty string (required).

  • query?: object with string|number|boolean|string[] values.

  • body?: any JSON value.

  • headers?: object of string headers.

  • authorizationKey?: non-empty string.

• Expected data shape:

  • Jira HTTP response envelope.

• Common failures:

  • Invalid HTTP method/path.

  • Jira validation errors for body/query.

  • Unauthorized mutation key.

• Safety warnings:

  • This tool can call destructive endpoints (for example delete issue).

  • Confirm endpoint semantics in Atlassian docs before executing mutating methods.

• Recommended tools:

  • Prerequisite: jira_connection_info, jira_list_operations.

  • Follow-up: resource-specific read tool for verification.

• Example:

  {
    "name": "jira_api_request",
    "arguments": {
      "method": "GET",
      "path": "/issue/ENG-123",
      "query": { "fields": ["summary", "status"] }
    }
  }

Registering the MCP server

VS Code / local stdio

{
  "mcpServers": {
    "jira-mcp": {
      "command": "npm",
      "args": ["run", "start:stdio"],
      "cwd": "/Users/lesterjohn/Documents/GitHub/jira-mcp"
    }
  }
}

HTTP transport

Run:

npm run start:http

Default URLs:

• MCP: http://127.0.0.1:3000/mcp

• Health: http://127.0.0.1:3000/healthz

Environment variables

Core

• APP_NAME (default jira)

• MCP_SERVER_NAME (default jira-mcp)

• MCP_SERVER_VERSION

• MCP_ADMIN_AUTH_KEY

• MCP_TRANSPORT_MODE (stdio, http, both)

Jira service integration

• JIRA_BASE_URL (e.g. https://your-domain.atlassian.net)

• JIRA_TIMEOUT_MS

• JIRA_AUTH_MODE (none, bearer, basic)

• JIRA_BEARER_TOKEN

• JIRA_BASIC_USERNAME

• JIRA_BASIC_PASSWORD (use Jira API token for basic auth)

• JIRA_API_PREFIX (default /rest/api/3)

HTTP transport gate

• MCP_HTTP_HOST, MCP_HTTP_PORT, MCP_HTTP_PATH, MCP_HTTP_HEALTH_PATH

• MCP_HTTP_AUTH_MODE (token)

• MCP_HTTP_AUTH_TOKENS

• MCP_HTTP_ALLOWED_ORIGINS

• MCP_HTTP_ALLOWED_IPS

• MCP_HTTP_MAX_BODY_BYTES

• MCP_HTTP_RATE_LIMIT_WINDOW_MS

• MCP_HTTP_RATE_LIMIT_MAX_REQUESTS

Postgres / Vault support (retained from skeleton)

• POSTGRES_HOST, POSTGRES_PORT, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD

• VAULT_ADDR, VAULT_TOKEN

Quick start

1. Install dependencies: npm install

2. Copy .env.example to .env

3. Fill in Jira credentials (JIRA_BASE_URL, auth variables)

4. Start server:

   • stdio: npm run start:stdio

   • HTTP: npm run start:http

5. Run tests: npm test

External Services Mode

This repository keeps the skeleton's app-only mode for external infrastructure, including docker-compose.external.yml.

Use this mode when Vault and Postgres are managed outside this repository.

Required environment variables include:

• POSTGRES_HOST, POSTGRES_PORT, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD

• VAULT_ADDR, VAULT_TOKEN

Run:

docker compose -f docker-compose.external.yml up -d

Notes on "full coverage"

Jira REST v3 has a very large endpoint surface. This solution provides practical full coverage by combining:

• high-value first-class tools for common Jira workflows

• operation-key execution for curated documented endpoints

• unrestricted Jira REST pass-through via jira_api_request

That means any Jira REST path documented by Atlassian can be called through MCP without waiting for a dedicated wrapper tool.

License

This project is licensed under the MIT License. See LICENSE.