Opencode Jira

MCP (Model Context Protocol) server that connects opencode with Jira Cloud, exposing issue tracking, project management, and agile features as structured tools for AI agents.

GitHub Packages CI License: MIT

---

Requirements

• Node.js >= 18
• A Jira Cloud account with an API token
• An MCP client (such as opencode, Claude Desktop, or any MCP-compatible host)

Installation

1. Authenticate with GitHub Packages

Create or edit your ~/.npmrc file and add:

//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
@DevelopmentAgentSDD:registry=https://npm.pkg.github.com

Get a GitHub token at Settings → Developer settings → Personal access tokens → Tokens (classic) with the read:packages scope.

2. Global install (recommended)

npm install -g @DevelopmentAgentSDD/opencode-jira-mcp

3. Using npx (no install)

npx @DevelopmentAgentSDD/opencode-jira-mcp

From source

git clone https://github.com/DevelopmentAgentSDD/MCP-JiraCloud.git
cd MCP-JiraCloud
npm ci
npm run build

Configuration

The server requires three environment variables:

Variable	Description
JIRA_HOST	Your Jira Cloud domain (e.g., my-company.atlassian.net) — do not include https://
JIRA_EMAIL	Email address of your Atlassian account
JIRA_API_TOKEN	API token generated at https://id.atlassian.com/manage-profile/security/api-tokens

Configuring in opencode

Add the server to your opencode.json:

{
  "mcp": {
    "jira": {
      "type": "local",
      "command": ["npx", "-y", "@DevelopmentAgentSDD/opencode-jira-mcp"],
      "env": {
        "JIRA_HOST": "my-company.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Security tip: avoid hardcoding the token. Use {env:JIRA_API_TOKEN} interpolation so opencode reads it from the environment at runtime.

Configuring in Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@DevelopmentAgentSDD/opencode-jira-mcp"],
      "env": {
        "JIRA_HOST": "my-company.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Available Tools

The server exposes 9 tools to the MCP host:

1. search_issues

Search for issues in Jira using structured parameters or raw JQL.

"Find all high-priority bugs in the PROJ project assigned to me"
"Search for issues containing 'login' in the summary or description"

Parameters: projectKey, issueType, status, assignee, priority, labels, sprint, text, jql, startAt, maxResults, orderBy, fields

2. create_issue

Create a new Jira issue of any type (Task, Bug, Story, Epic, Subtask).

"Create a bug in PROJ: 'Login page crashes on mobile' with priority High"
"Create an Epic called 'Q2 Platform Migration' in the PROJ project"

Parameters: projectKey, summary, issueType, description, priority, assignee, labels, parentKey (Subtask), epicName (Epic)

3. update_issue

Modify fields on an existing Jira issue.

"Update PROJ-123: change priority to Critical, add label 'security'"
"Set the assignee of PROJ-456 to unassigned"

Parameters: issueKey, summary, description, priority, labels, assignee, components, customFields

4. transition_issue

Move an issue through its workflow or list available transitions.

"Move PROJ-123 to In Progress"
"What transitions are available for PROJ-456?"
"Close PROJ-789 with resolution 'Done'"

Parameters: issueKey, transitionName, transitionId, resolution, comment, listTransitions

5. get_sprints

Retrieve sprints from a Jira board with optional issue details.

"Show me active sprints on the PROJ Scrum Board"
"List all sprints on board ID 42, including their issues"

Parameters: boardId, boardName, state (active|future|closed), includeIssues, startAt, maxResults

6. assign_user

Assign or unassign a user to/from an issue.

"Assign PROJ-123 to John Doe"
"Unassign PROJ-456"

Parameters: issueKey, accountId (set to null or "unassigned" to unassign)

7. manage_comments

List or add comments on a Jira issue.

"Show all comments on PROJ-123"
"Add a comment to PROJ-123: 'Fixed in PR #42, ready for review'"

Parameters: action (list|add), issueKey, body (for add), startAt, maxResults

8. attach_file

Attach a file from the local filesystem to a Jira issue.

"Attach the file error-screenshot.png to PROJ-123"

Parameters: issueKey, filePath (must exist, be readable, and <10 MB)

9. jira_health_check

Verify connectivity to Jira Cloud and validate authentication credentials.

"Check if the Jira connection is working"

Parameters: none

Security

• Token safety: the JIRA_API_TOKEN is never written to stdout, stderr, or error messages. All log entries and error responses redact the token.
• Headers sanitization: Authorization headers are replaced with Basic [REDACTED] in all logs.
• Config sanitization: when logging the configuration, the token is displayed as ***SET***.
• Token rotation: generate new tokens at https://id.atlassian.com/manage-profile/security/api-tokens. The server picks up the new token on restart.

Troubleshooting

"JIRA_HOST is required"

Set the JIRA_HOST environment variable to your Jira Cloud domain without https://:

export JIRA_HOST=my-company.atlassian.net

"JIRA_API_TOKEN is required"

Generate an API token at https://id.atlassian.com/manage-profile/security/api-tokens and set it:

export JIRA_API_TOKEN=your-generated-token

"Authentication failed"

• Verify your email matches the Atlassian account email
• Ensure the API token is active (not revoked)
• Check that JIRA_HOST is correct and does not include https://

"Access denied"

Your account does not have permission for the requested action. Verify your project permissions in Jira.

"Rate limit exceeded"

The server automatically retries with exponential backoff (up to 3 retries, max ~210s total). If you consistently hit rate limits, reduce request frequency or check your Jira Cloud plan limits.

Development

# Install dependencies
npm ci

# Run in development mode (with auto-reload)
npm run dev

# Type check
npm run typecheck

# Lint
npm run lint

# Format
npm run format

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build for production
npm run build

Project structure

src/
  index.ts                  # Entry point (shebang, main function)
  config/                   # Zod-based env var validation
  auth/                     # Basic Auth header builder
  services/                 # JiraClient (HTTP client with retry)
  tools/                    # 9 MCP tool handlers + centralized registration
  transport/                # Stdio transport setup
  types/                    # TypeScript interfaces
  utils/                    # Errors, retry logic, sanitization
tests/
  unit/                     # Unit tests (vitest)
  integration/              # Integration tests (nock for HTTP mocking)
  fixtures/                 # Mock Jira responses

Tech stack

Category	Technology
Language	TypeScript 5.5+ (strict mode)
Runtime	Node.js >= 18
MCP SDK	@modelcontextprotocol/sdk ^1.0
Validation	Zod ^3.24
Logging	Pino ^9.0
Testing	Vitest + nock
Linting	ESLint + Prettier

License

MIT — see LICENSE for details.