jira-interface

Local JIRA interface with CLI commands and an MCP (Model Context Protocol) server. Built in Rust on top of gouqi for the JIRA REST API and rmcp for MCP.

Quick Start

# Build
cargo build --release

# Set up credentials (opens browser for API token creation)
./target/release/jira-interface setup

# Use the CLI
./target/release/jira-interface create -p PROJ -s "My issue" -t Story
./target/release/jira-interface comment PROJ-1 -m "A comment"
./target/release/jira-interface link PROJ-1 --type blocks PROJ-2

# Start the MCP server
./target/release/jira-interface serve

Setup

Run jira-interface setup to configure credentials interactively. It will:

1. Prompt for your JIRA instance URL (e.g. https://yourcompany.atlassian.net)
2. Open your browser to Atlassian's API token page
3. Prompt for your email and the generated token
4. Write the config to ~/.config/jira-interface/config.toml
5. Test the connection

The config file looks like:

jira_url = "https://yourcompany.atlassian.net"

[auth]
method = "basic"
username = "you@company.com"
token = "your-api-token"

Other auth methods supported:

# Bearer token (OAuth 2.0 / Jira Cloud)
[auth]
method = "bearer"
token = "your-bearer-token"

# Personal Access Token (Jira Server/Data Center)
[auth]
method = "pat"
token = "your-pat"

CLI Commands

create - Create an issue

jira-interface create \
  -p PROJ \
  -s "Issue summary" \
  -d "Description text" \
  -t Story \
  --priority High \
  -l "label1,label2" \
  -a username

Flag	Required	Description
-p, --project	yes	Project key (e.g. PROJ)
-s, --summary	yes	Issue title
-d, --description	no	Issue description
-t, --issue-type	no	Issue type (default: Task)
--priority	no	Priority name (High, Medium, Low)
-l, --labels	no	Comma-separated labels
-a, --assignee	no	Assignee username

link - Link two issues

jira-interface link PROJ-1 --type blocks PROJ-2
jira-interface link PROJ-3 --type relates-to PROJ-4 -c "These are related"

Link types: blocks, blocked-by, relates-to, duplicates, duplicated-by, clones, cloned-by.

comment - Add a comment

# Inline message
jira-interface comment PROJ-1 -m "Fixed in latest PR"

# From a file
jira-interface comment PROJ-1 -f notes.md

# From stdin
echo "Deployed to staging" | jira-interface comment PROJ-1 --stdin

setup - Configure credentials

jira-interface setup

serve - Start MCP server

jira-interface serve

Starts an MCP server on stdio. See MCP Server below.

MCP Server

The serve command starts an MCP server over stdio transport, exposing 28 JIRA tools. Add it to your MCP client config:

{
  "mcpServers": {
    "jira": {
      "command": "/path/to/jira-interface",
      "args": ["serve"]
    }
  }
}

Tools

Issue Operations

Tool	Description
create_issue	Create a new issue (project, summary, type, description, priority, labels, assignee)
edit_issue	Update fields on an existing issue
get_issue	Get full details of an issue
search_issues	Search with JQL
link_issues	Link two issues (blocks, relates, duplicates, cloners)

Comments & Worklogs

Tool	Description
add_comment	Add a comment to an issue
add_worklog	Log time against an issue

Workflow

Tool	Description
get_transitions	List available transitions for an issue
transition_issue	Move an issue through its workflow

Users & Watchers

Tool	Description
lookup_user	Search users by name or email
get_watchers	List watchers on an issue
manage_watcher	Add or remove a watcher

Projects & Metadata

Tool	Description
list_projects	List visible projects
get_project_issue_types	List issue types for a project
get_issue_type_fields	Get field metadata for creating issues
list_resolutions	List available resolutions

Attachments & Links

Tool	Description
list_attachments	List files attached to an issue
get_remote_links	List remote links on an issue (Confluence, external URLs)

History

Tool	Description
get_changelog	Get field change history for an issue

Sprint Management

Tool	Description
list_boards	List Agile boards
list_sprints	List sprints for a board
get_sprint	Get sprint details
move_issues_to_sprint	Move issues into a sprint
sprint_plan	Auto-plan a sprint from backlog by priority with capacity limit

Bulk Operations

Tool	Description
bulk_create_issues	Create multiple issues at once
create_epic_with_children	Create an Epic with linked child issues
bulk_transition	Transition multiple issues at once
bulk_assign	Assign/unassign multiple issues
bulk_label	Add/remove labels across multiple issues

Architecture

src/
  main.rs       Entry point — CLI parsing, dispatches to commands or MCP server
  cli.rs        clap definitions for create/link/comment/serve/setup subcommands
  commands.rs   CLI command implementations (create, link, comment)
  config.rs     TOML config loading from ~/.config/jira-interface/config.toml
  client.rs     gouqi Jira client construction from config
  mcp.rs        MCP server (28 tools) using rmcp with stdio transport
  setup.rs      Interactive setup flow — browser-based API token creation

Key Design Decisions

• gouqi for JIRA API: Covers issues, search, transitions, sprints, boards, users, worklogs, attachments, and more. Supports both JIRA Cloud (v3/ADF) and Server/Data Center (v2). Where gouqi lacks coverage (remote links, changelog, issue type metadata), raw API calls are used via jira.get()/jira.post().

• rmcp for MCP: Official Rust MCP SDK. Tools are defined with #[tool] macros that auto-generate JSON Schema for parameters. Stdio transport for easy integration with Claude Code, Cursor, and other MCP clients.

• Sync gouqi + async rmcp: gouqi uses blocking HTTP (reqwest::blocking), while rmcp is async. Each MCP tool dispatches to tokio::task::spawn_blocking to avoid blocking the async event loop.

• Lightweight issue creation: gouqi's built-in CreateIssue struct requires all fields. We use CreateCustomIssue<T> with a custom CreateFields struct that only serializes fields that are set, matching what the JIRA REST API actually requires.

• Bulk operations are fault-tolerant: They process all items and report per-item success/failure rather than aborting on first error.

Dependencies

Crate	Purpose
gouqi	JIRA REST API client (sync + async, v2/v3, OAuth/Basic/Bearer/PAT)
rmcp	MCP server SDK (official Rust implementation)
clap	CLI argument parsing
tokio	Async runtime (for MCP server)
serde / serde_json	Serialization
schemars	JSON Schema generation for MCP tool parameters
toml	Config file parsing
dirs	Platform config directory resolution
open	Cross-platform browser launching (for setup)
anyhow	Error handling
libc	Terminal echo control (hidden password input on Unix)
tracing-subscriber	Log output for MCP server