@crypto512/jicon-mcp

v2.4.2

Published

a month ago

Model Context Protocol server for Jira, Confluence, and Tempo integration

0High
0Medium
0Low

crypto512x

mcp model-context-protocol jira confluence atlassian ai claude

Jicon - Jira & Confluence MCP Server

Data Center Focus: This MCP server is designed and tested for Atlassian Data Center (Jira 9.x+, Confluence 8.x+, Tempo 3.x+). Cloud instances may work but are not the primary target.

Connect your AI assistant to Jira, Confluence, and Tempo. Search issues, create pages, log time - all through natural conversation.

Quick Start

# Run with npx (no installation required)
npx @crypto512/jicon-mcp

# Or install globally
npm install -g @crypto512/jicon-mcp

What Can You Do?

Once configured, just ask in natural language:

Jira

"Find all high-priority bugs assigned to me"
"What happened on project ACME this week?" (Activity digest)
"Create a task for implementing user authentication"
"Move PROJ-123 to Done and add a comment that it's deployed"
"Analyze the current sprint - any risks or blockers?" (Sprint analysis)
"Summarize recent discussions about authentication" (Comment analysis)
"Link PROJ-456 as blocking PROJ-789"

Confluence

"Update the API documentation page with the new endpoints"
"Create a meeting notes page in the Engineering space"
"Find all pages about authentication in DOCS"
"Add a PlantUML diagram to the architecture page"

Tempo

"Log 4 hours on PROJ-123 for today with description 'Code review'"
"Show my worklogs for this week"
"How much time did the team spend on the Epic last month?"

Setup

Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "jicon": {
      "command": "npx",
      "args": ["-y", "@crypto512/jicon-mcp"],
      "env": {
        "JIRA_URL": "https://jira.example.com",
        "JIRA_API_TOKEN": "your-api-token",
        "CONFLUENCE_URL": "https://confluence.example.com",
        "CONFLUENCE_API_TOKEN": "your-api-token"
      }
    }
  }
}

Claude Code

Add to ~/.claude/settings.json or project .mcp.json:

{
  "mcpServers": {
    "jicon": {
      "command": "npx",
      "args": ["-y", "@crypto512/jicon-mcp"],
      "env": {
        "JIRA_URL": "https://jira.example.com",
        "JIRA_API_TOKEN": "your-api-token",
        "CONFLUENCE_URL": "https://confluence.example.com",
        "CONFLUENCE_API_TOKEN": "your-api-token"
      }
    }
  }
}

OpenCode

Add to opencode.jsonc in your project root or ~/.config/opencode/opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jicon": {
      "type": "local",
      "command": ["npx", "-y", "@crypto512/jicon-mcp"],
      "environment": {
        "JIRA_URL": "https://jira.example.com",
        "JIRA_API_TOKEN": "your-api-token",
        "CONFLUENCE_URL": "https://confluence.example.com",
        "CONFLUENCE_API_TOKEN": "your-api-token"
      }
    }
  }
}

Configuration

All configuration is done through environment variables.

Environment Variables

| Variable | Type | Default | Description | |----------|------|---------|-------------| | JIRA_URL | string | - | Jira instance URL | | JIRA_USERNAME | string | - | Email (omit for Data Center PAT) | | JIRA_API_TOKEN | string | - | API token or Personal Access Token | | JIRA_AUTH_TYPE | basic|bearer | auto | Auth type (auto-detected from username) | | CONFLUENCE_URL | string | - | Confluence instance URL | | CONFLUENCE_USERNAME | string | - | Email (omit for Data Center PAT) | | CONFLUENCE_API_TOKEN | string | - | API token or Personal Access Token | | CONFLUENCE_AUTH_TYPE | basic|bearer | auto | Auth type (auto-detected from username) | | JICON_PERMISSIONS_MODE | readonly|full|custom | readonly | Permission mode | | JICON_PERMISSIONS_WHITELIST | comma-separated | - | Tools to allow (custom mode) | | JICON_PERMISSIONS_BLACKLIST | comma-separated | - | Tools to deny (custom mode) | | JICON_PLANTUML_SERVER_URL | string | - | PlantUML server URL (e.g., http://localhost:8080) | | JICON_MAX_OUTPUT | number | 32000 | Maximum output characters | | JICON_MAX_BUFFER_SIZE | number (KB) | 10240 | Maximum buffer size in KB (10 MB). Arrays truncated cleanly. | | JICON_MAX_API_RESULTS | number | 5000 | Maximum items fetched from any paginated API call | | JICON_DEFAULT_PERIOD | string | 30d | Default time period for activity tools (e.g., 7d, 30d, 365d) | | JICON_HTTP_TIMEOUT | number (ms) | 60000 | HTTP request timeout per API call (milliseconds) | | JICON_TRANSPORT | stdio|http | stdio | Transport mode (use http for containers) | | JICON_HTTP_PORT | number | 3000 | HTTP server port | | JICON_HTTP_HOST | string | 0.0.0.0 | HTTP bind address | | JICON_HTTP_BASE_PATH | string | /mcp | MCP endpoint path | | JICON_LOG_LEVEL | error|warn|info|debug | info | Log verbosity level. Use debug for troubleshooting. |

Note: Tempo uses the same Jira credentials - no separate configuration needed.

Permission Modes

Control what operations are allowed. By default, Jicon runs in read-only mode - all read tools across Jira, Confluence, and Tempo are available, but no write operations.

1. Read-Only (default)

No special configuration needed. All read tools across Jira, Confluence, and Tempo.

{
  "env": {
    "JIRA_URL": "https://jira.example.com",
    "JIRA_API_TOKEN": "your-token"
  }
}

2. Full Access

All tools enabled — read, write, delete across all services.

{
  "env": {
    "JICON_PERMISSIONS_MODE": "full",
    "JIRA_URL": "https://jira.example.com",
    "JIRA_API_TOKEN": "your-token"
  }
}

3. Safe Write — Draft Only (human in the loop)

AI can read everything and create/save/delete Confluence drafts. User reviews and publishes via Confluence UI. No direct page modification.

{
  "env": {
    "JICON_PERMISSIONS_MODE": "custom",
    "JICON_PERMISSIONS_WHITELIST": "jira_read,confluence_read,confluence_write_draft,tempo_read"
  }
}

4. Direct Write — Home Space Only

AI can read everything and perform all Confluence write operations, but restricted to the user's personal space at runtime.

{
  "env": {
    "JICON_PERMISSIONS_MODE": "custom",
    "JICON_PERMISSIONS_WHITELIST": "jira_read,confluence_read,confluence_write_home,tempo_read"
  }
}

Write-Home Restriction: When confluence_write_home is in the whitelist, all Confluence write operations are validated at runtime to ensure they target the authenticated user's personal space. Attempts to write outside the personal space are blocked with a clear error message.

Custom Permissions

For fine-grained control, use custom mode with whitelist or blacklist:

{
  "env": {
    "JICON_PERMISSIONS_MODE": "custom",
    "JICON_PERMISSIONS_WHITELIST": "jira_all,confluence_all,tempo_all",
    "JICON_PERMISSIONS_BLACKLIST": "confluence_delete_page,tempo_delete_worklog"
  }
}

Virtual actions (for whitelist): jira_read, jira_write, jira_all, confluence_read, confluence_write, confluence_write_draft, confluence_write_home, confluence_draft, confluence_all, tempo_read, tempo_write, tempo_all

Individual tools (for blacklist): See TOOL_LIST.md for all tool names

PlantUML Configuration

PlantUML validation requires an external PlantUML server. If not configured, PlantUML tools are disabled.

Configure PlantUML server:

{
  "env": {
    "JICON_PLANTUML_SERVER_URL": "http://localhost:8080"
  }
}

You can use the public PlantUML server (http://www.plantuml.com/plantuml) or run your own with Docker: docker run -d -p 8080:8080 plantuml/plantuml-server:jetty.

Authentication

Atlassian Cloud

Go to https://id.atlassian.com/manage-profile/security/api-tokens
Create a new API token
Use your email as username and the token as token

Jira/Confluence Data Center (8.14+)

Go to your profile → Personal Access Tokens
Create a new token
Use only the token field (omit username)
Optionally set "authType": "bearer"

Requirements

Node.js 18+
Jira Server/Data Center or Cloud with API access
Confluence (optional) Server/Data Center or Cloud
Tempo (optional) Timesheets plugin
PlantUML Server (optional) External server for diagram validation

Docker Deployment

Jicon supports two transport modes:

| Mode | Use Case | Protocol | |------|----------|----------| | stdio (default) | Local usage with npx, Claude Desktop, Claude Code | Standard I/O | | http | Containers, remote servers | HTTP with StreamableHTTP |

For containerized deployments, use HTTP mode which exposes the MCP protocol over HTTP.

Running with Docker

1. Build the image:

docker build -t jicon-mcp .

2. Run the container:

docker run -d -p 3000:3000 \
  -e JIRA_URL=https://jira.example.com \
  -e JIRA_API_TOKEN=your-api-token \
  -e CONFLUENCE_URL=https://confluence.example.com \
  -e CONFLUENCE_API_TOKEN=your-api-token \
  --name jicon-mcp \
  jicon-mcp

The container automatically uses HTTP transport (JICON_TRANSPORT=http).

3. Verify it's running:

curl http://localhost:3000/health
# Returns: {"status":"ok"}

Running with Docker Compose

1. Create a .env file with your credentials:

cat > .env << 'EOF'
JIRA_URL=https://jira.example.com
JIRA_API_TOKEN=your-api-token
CONFLUENCE_URL=https://confluence.example.com
CONFLUENCE_API_TOKEN=your-api-token
EOF

2. Start the service:

docker-compose up -d

3. View logs:

docker-compose logs -f

HTTP Transport Configuration

| Variable | Default | Description | |----------|---------|-------------| | JICON_TRANSPORT | stdio | Transport mode: stdio or http | | JICON_HTTP_PORT | 3000 | HTTP server port | | JICON_HTTP_HOST | 0.0.0.0 | HTTP bind address | | JICON_HTTP_BASE_PATH | /mcp | MCP endpoint path |

Note: Sessions are automatically cleaned up after 1 hour of inactivity (no tool calls). MCP clients should set their timeout based on expected tool execution time (e.g., 5 minutes for most operations).

HTTP Endpoints

| Endpoint | Method | Description | |----------|--------|-------------| | /health | GET | Health check - returns {"status":"ok"} | | /ready | GET | Readiness check - returns {"status":"ready"} | | /mcp | ALL | MCP protocol endpoint (StreamableHTTP) |

Connecting MCP Clients

Once the HTTP server is running, connect your MCP client to http://localhost:3000/mcp:

# Using MCP Inspector
npx @modelcontextprotocol/inspector --url http://localhost:3000/mcp

Running HTTP Mode Locally (without Docker)

For development or testing, you can run HTTP mode directly:

# Using npm script
npm run start:http

# Or with environment variables
JICON_TRANSPORT=http \
  JIRA_URL=https://jira.example.com \
  JIRA_API_TOKEN=your-token \
  npm start

LibreChat Integration

LibreChat supports MCP servers via the streamable-http transport type. This allows LibreChat to connect to jicon running in a container.

Each LibreChat user can use their own Jira/Confluence credentials via HTTP headers. Configure customUserVars in LibreChat to prompt users for their credentials:

# librechat.yaml
mcpServers:
  jicon:
    type: streamable-http
    url: http://jicon-mcp:3000/mcp
    timeout: 180000
    initTimeout: 10000
    headers:
      X-Jira-Url: "{{JIRA_URL}}"
      X-Jira-Token: "{{JIRA_TOKEN}}"
      X-Confluence-Url: "{{CONFLUENCE_URL}}"
      X-Confluence-Token: "{{CONFLUENCE_TOKEN}}"
    customUserVars:
      JIRA_URL:
        title: "Jira URL"
        description: "Your Jira instance URL (e.g., https://jira.example.com)"
      JIRA_TOKEN:
        title: "Jira Token"
        description: "Your Jira Personal Access Token"
      CONFLUENCE_URL:
        title: "Confluence URL"
        description: "Your Confluence instance URL"
      CONFLUENCE_TOKEN:
        title: "Confluence Token"
        description: "Your Confluence Personal Access Token"
    serverInstructions: |
      Jicon MCP server provides access to Jira, Confluence, and Tempo.
      Use jicon_help tool to learn about available workflows.

Per-user credential headers:

| Header | Description | |--------|-------------| | X-Jira-Url | Jira instance URL | | X-Jira-Token | Jira API token (PAT) | | X-Confluence-Url | Confluence instance URL | | X-Confluence-Token | Confluence API token (PAT) |

Both URL and Token headers must be provided together for each service. Per-request credentials take priority over environment variables.

For more details, see LibreChat MCP documentation.

API Limitations

Confluence Draft Limitations (Data Center REST API)

The Confluence Data Center REST API has specific limitations for draft management:

| Operation | Support | |-----------|---------| | Create new draft | Yes - POST /content?status=draft | | Read draft | Yes - GET /content/{id}?status=draft | | Update draft | No - API doesn't support updating drafts | | Delete draft | Yes - DELETE /content/{id}?status=draft | | Create draft for existing page | No - Only new standalone drafts |

Why "[jicon-mcp REVIEW]" workflow?

Since the API cannot create a "draft version" of an existing page, Jicon uses a workaround:

Creates a [jicon-mcp REVIEW] Title draft linked to the original via label
User reviews the draft content
User approves to publish changes to the original page

This achieves "draft before publish" semantics within API constraints.

Rate Limits

Atlassian Cloud: Subject to API rate limits (varies by plan)
Data Center: Typically no rate limits, but large queries may timeout
Jicon defaults: Searches fetch up to 5000 results, paginated automatically

Features

85 Tools Across 3 Services

| Service | Capabilities | |---------|--------------| | Jira (29 tools) | Search, create, update, transition issues; manage comments, links, watchers; access boards, sprints, worklogs; user search; LLM-powered analysis | | Confluence (21 tools) | Search, create, edit pages via drafts; manage spaces, comments, attachments; PlantUML diagrams; review workflow | | Tempo (13 tools) | Log time, view/update worklogs, team tracking, accounts |

Plus utility tools for content buffering, time calculations, URL generation, date resolution, and built-in help.

LLM-Powered Analysis Tools

These intelligent entry points are designed for AI synthesis - they return pre-processed content directly to the LLM (not buffered) for analysis and insight generation:

| Tool | Purpose | |------|---------| | Activity Digest | Fetches comments, status/priority/assignee changes across issues. Ask: "What happened on project X this week?" | | Recent Comments | Aggregates comments across multiple issues. Ask: "Any blockers mentioned in recent discussions?" | | Changelog | Tracks field changes across issues. Ask: "What issues had priority escalations?" | | Analyze Epic | Comprehensive Epic analysis: hierarchy breakdown, time metrics, velocity, linked Confluence pages, recent discussions. Ask: "Analyze Epic PROJ-100 for progress and risks" |

These tools return markdown formatted for LLM comprehension with pre-computed summaries (counts, breakdowns), enabling the AI to focus on insight and synthesis rather than data extraction.

Buffered Responses

All data-heavy tools (search, list, get) return buffered responses for efficient handling of large datasets. Instead of returning raw data, tools return a bufferId with metadata:

Buffer capabilities:

Read content in chunks or search within buffered data
JavaScript-based transformation: write custom code to filter, transform, aggregate data
Built-in helpers: groupBy, sum, avg, min, max, unique, date utilities
Generate Confluence tables and lists with auto-linking and conditional formatting
Track buffer origin with metadata (resource type, query, title)

Safe Confluence Editing (Review Workflow)

Confluence write operations use a review workflow for safety:

Creating a New Page

Ask the AI: "Create a meeting notes page in the Engineering space"
Draft Created: Jicon creates a draft that only you can see
Review & Publish: You review and publish via Confluence UI

Editing an Existing Page

Ask the AI: "Add a PlantUML diagram to page https://confluence.example.com/..."
Review Draft Created: Jicon creates a [jicon-mcp REVIEW] Page Title draft linked to the original
You Review: Check the draft content in Confluence UI
Publish or Discard: Apply changes to the original page, discard them, or manually copy content

This means the AI assistant never directly modifies existing pages - all changes are staged as review drafts that require your approval. Combined with the confluence_write_home permission profile, this ensures complete control over what gets published.

PlantUML Diagrams

Create and validate UML diagrams directly in Confluence pages. Configure JICON_PLANTUML_SERVER_URL to enable diagram validation. If not configured, PlantUML tools return clear errors explaining how to enable them.

Tool Reference

For complete tool documentation with parameters and examples, see TOOL_LIST.md.

Upgrading to 2.4.1? Tool names were standardized for consistency (a breaking change). See the Breaking changes in 2.4.1 table for the old → new mapping.

Troubleshooting

Debug Mode

Enable debug logging to diagnose API issues:

{
  "env": {
    "JICON_LOG_LEVEL": "debug"
  }
}

This logs all requests and responses to stderr with timestamps and [DEBUG] prefix:

Request method, URL, headers (tokens masked), and body
Response status, headers, and body (truncated for large responses)

Note: Debug output may include sensitive information. Only enable for troubleshooting.

Other Hidden Options

| Variable | Default | Description | |----------|---------|-------------| | JICON_KEEP_NULLS | false | Preserve null values in JSON responses (increases token usage) |

Security

Store credentials in environment variables, not in code
Use API tokens with minimal required permissions
Rotate tokens regularly
Use read-only mode for exploration
Never commit credentials to version control

License

MIT License - see LICENSE for details.

Support

Acknowledgments

Built on Model Context Protocol by Anthropic.

Made with care for teams using Jira, Confluence, and Tempo