mcp-atlassian-ts

Bazilio-san/mcp-atlassian-ts

3.2

If you are the rightful owner of mcp-atlassian-ts and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

MCP Atlassian TypeScript Server is a modern server designed for Atlassian JIRA and Confluence, offering a robust architecture and comprehensive features.

Tools
55
Resources
0
Prompts
0

MCP Atlassian TypeScript Server

Modern TypeScript MCP server for Atlassian JIRA and Confluence with comprehensive features and robust architecture.

🚀 Features

  • 🔧 51 MCP Tools: Complete coverage of JIRA (34 tools) and Confluence (17 tools) operations
  • ⚡ Modern TypeScript: Built with ES2022, strict type checking, and comprehensive error handling
  • 🔐 Multiple Authentication: Basic Auth, Personal Access Tokens (PAT), and OAuth 2.0 support
  • 🚀 Service Modes: Run JIRA-only, Confluence-only, or combined server modes
  • 🌐 Transport Options: STDIO for Claude Desktop, HTTP for testing, SSE experimental
  • 📊 Performance: TTL-based caching, rate limiting, and optimized API calls
  • 🧪 Testing: Comprehensive test suite with JIRA emulator and API endpoint coverage
  • 📦 Docker Ready: Containerized deployment with configuration management

📦 Quick Start

Installation

git clone https://github.com/Bazilio-san/mcp-atlassian-ts.git
cd mcp-atlassian-ts
npm install

Configuration

cp .env.example .env
# Edit .env with your Atlassian credentials

Run

# Development mode with hot reload
npm run dev

# Production mode
npm run build
npm start

🔧 Configuration

Configuration uses a two-layer approach:

  • config.yaml - Primary configuration file for all application settings
  • .env - Environment variables for sensitive data only (URLs, credentials)

Primary Configuration (config.yaml)

Copy config.yaml.example to config.yaml and customize:

# Server settings
server:
  port: 3000
  host: '0.0.0.0'
  transportType: http               # 'stdio', 'http', or 'sse'
  serviceMode: jira                 # 'jira' or 'confluence'

# Logging
logging:
  level: info                       # 'debug', 'info', 'warn', 'error'
  pretty: true

# Performance & Caching
cache:
  ttlSeconds: 300
  maxItems: 1000

rateLimit:
  windowMs: 900000
  maxRequests: 100

# JIRA Configuration
jira:
  url: ${JIRA_URL}                  # From environment variable
  maxResults: 50
  fieldId:
    epicLink: customfield_10008
    epicName: customfield_10011
    storyPoints: customfield_10024

  # Authentication via environment variables
  auth:
    basic:
      username: ${JIRA_USERNAME}
      password: ${JIRA_PASSWORD}    # API token recommended
    # pat: ${JIRA_PAT}             # Alternative: Personal Access Token

  # Tool Configuration
  usedInstruments:
    include: ALL                    # Enable all JIRA tools
    exclude: []                     # Or exclude specific tools

# Confluence Configuration
confluence:
  url: ${CONFLUENCE_URL}            # From environment variable
  maxResults: 50

  # Authentication via environment variables
  auth:
    basic:
      username: ${CONFLUENCE_USERNAME}
      password: ${CONFLUENCE_PASSWORD}
    # pat: ${CONFLUENCE_PAT}       # Alternative: Personal Access Token

  # Tool Configuration
  usedInstruments:
    include: ALL                    # Enable all Confluence tools
    exclude: []                     # Or exclude specific tools

Environment Variables (.env)

Copy .env.example to .env and fill in your credentials:

# JIRA Authentication (Required for JIRA service)
JIRA_URL=https://your-company.atlassian.net
JIRA_USERNAME=your-login
JIRA_PASSWORD=your-api-token-or-password 

# Alternative: Personal Access Token
# JIRA_PAT=your-personal-access-token

# Confluence Authentication (Required for Confluence service)
CONFLUENCE_URL=https://your-company.atlassian.net/wiki
CONFLUENCE_USERNAME=your-login
CONFLUENCE_PASSWORD=your-api-token-or-password

# Alternative: Personal Access Token
# CONFLUENCE_PAT=your-personal-access-token

🔐 Authentication Methods

The server supports multiple authentication methods for flexibility:

Basic Authentication (Recommended)

JIRA_USERNAME=your-login
JIRA_PASSWORD=your-api-token-or-password

Personal Access Token (PAT)

JIRA_PAT=your-personal-access-token

OAuth 2.0 (Future)

JIRA_OAUTH_CLIENT_ID=your-client-id
JIRA_OAUTH_CLIENT_SECRET=your-client-secret

For detailed authentication setup, see Atlassian API Documentation.

🏃‍♂️ Usage

Development Mode

# Development with hot reload
npm run dev

# Service-specific development
npm run dev:jira        # JIRA-only mode
npm run dev:confluence  # Confluence-only mode
npm run dev:stdio       # STDIO transport

Production Mode

# Build and start
npm run build
npm start

# Service-specific modes
npm run start:jira        # JIRA-only server
npm run start:confluence  # Confluence-only server

Docker Deployment

# Build and run
npm run docker:build
npm run docker:run

# Or manually
docker build -t mcp-atlassian-ts .
docker run -p 3000:3000 --env-file .env mcp-atlassian-ts

🛠️ Complete Tool List

🎯 JIRA Tools (34 tools) {#jira-tools}

Core Issue Management (9 tools) {#jira-core}
Project Management (8 tools) {#jira-projects}
Agile/Scrum (6 tools) {#jira-agile}
Issue Links (4 tools) {#jira-links}
Comments & Epic Links (3 tools) {#jira-comments}
Worklog Management (2 tools) {#jira-worklog}
Metadata & Search (2 tools) {#jira-metadata}
Attachments (1 tool) {#jira-attachments}

📝 Confluence Tools (17 tools) {#confluence-tools}

Content Management (6 tools) {#confluence-content}
Space Management (3 tools) {#confluence-spaces}
Collaboration (5 tools) {#confluence-collaboration}
Navigation & History (3 tools) {#confluence-navigation}

🔧 Utility Tools (3 tools) {#utility-tools}

Integration Testing

The project includes comprehensive testing infrastructure:

JIRA Emulator
node tests/emulator/jira.js
  • Self-contained JIRA API emulator on port 8080
  • Test data: project TEST, issues TEST-1/TEST-2
  • No external dependencies required
Complete Test Flow
# Terminal 1: Start JIRA emulator
node tests/emulator/jira.js

# Terminal 2: Start MCP server
npm start

# Terminal 3: Run MCP tests
node tests/mcp/jira.js
API Endpoint Testing
# Terminal 1: Start JIRA emulator
node tests/emulator/jira.js

# Terminal 2: Run comprehensive API tests
node tests/endpoints/jira.js

Test Coverage:

  • ✅ 100% API endpoint coverage for JIRA REST API v2
  • ⚡ ~0.33s execution time for full test suite
  • 🔧 Self-contained testing with built-in emulator
  • 📊 Detailed test reporting and validation

🏗️ Architecture {#architecture}

src/
├── bootstrap/            # Application initialization and configuration
├── core/                # Core infrastructure systems
│   ├── auth/            # Authentication (Basic, PAT, OAuth2)
│   ├── server/          # MCP server with multiple transports
│   └── utils/           # Logging, caching, rate limiting, utilities
├── domains/             # Domain-specific implementations
│   ├── jira/            # JIRA client and 34 tools
│   └── confluence/      # Confluence client and 17 tools
├── types/               # TypeScript type definitions
└── index.ts             # Main entry point with CLI support

Key Components {#key-components}

  • MCP Server: Handles MCP protocol with STDIO/HTTP/SSE transports
  • Tool Registry: Manages 51 MCP tools with validation and execution
  • Authentication: Multi-method auth (Basic, PAT, OAuth2) with validation
  • Domain Managers: JIRA and Confluence specialized tool managers
  • Cache Layer: TTL-based caching with performance statistics
  • Error Handling: Comprehensive error types and context preservation

🌐 Transport Options {#transport-options}

STDIO (Default)

  • JSON-RPC 2.0 over stdin/stdout
  • Ideal for Claude Desktop and MCP clients
  • Direct integration without HTTP overhead

HTTP

  • RESTful API on port 3000
  • JSON-RPC 2.0 over HTTP
  • Web-based clients and testing
  • Health check at /health

SSE (Experimental)

  • Server-Sent Events for real-time updates
  • Persistent connections
  • Web applications with live updates

🌐 Transport Configuration Examples {#transport-examples}

Using with MCP Clients

Option A: Direct SSE Connection
{
  name: 'atlassian-mcp',
  sse: {
    url: 'https://your-domain.com/sse',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN'
    }
  }
}
Option B: Using mcp-remote Proxy (STDIO)

The mcp-remote proxy handles OAuth authentication for cloud services:

{
  name: 'atlassian-mcp',
  stdio: {
    command: 'npx',
    args: ['-y', 'mcp-remote', 'https://your-domain.com/sse']
  }
}

CLI Usage with mcp-remote

# Direct connection to SSE endpoint
npx -y mcp-remote https://your-domain.com/sse

# For older versions of mcp-remote, specify version
npx -y mcp-remote@0.1.13 https://your-domain.com/sse

💻 IDE Configuration {#ide-configuration}

VS Code

Create or edit .vscode/mcp.json:

For HTTP/SSE Transport:

{
  "servers": {
    "atlassian-mcp-server": {
      "url": "https://your-domain.com/sse",
      "type": "http"
    }
  },
  "inputs": []
}

For STDIO Transport:

{
  "servers": {
    "atlassian-mcp-server": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "MCP_SERVICE_MODE": "jira",
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your-login",
        "JIRA_PASSWORD": "your-api-token-or-password"
      }
    }
  }
}

Cursor

Add to MCP Settings:

Modern Configuration:

{
  "Atlassian-MCP-Server": {
    "url": "https://your-domain.com/sse"
  }
}

Legacy Configuration (STDIO):

{
  "mcp-atlassian-api": {
    "command": "npx",
    "args": [
      "mcp-remote",
      "https://your-domain.com/sse"
    ]
  }
}

Local Development Transport

For connecting to a locally running MCP server:

{
  name: 'local-atlassian',
  stdio: {
    command: 'node',
    args: ['dist/index.js'],
    env: {
      MCP_SERVICE_MODE: 'jira',
      JIRA_URL: 'http://localhost:8080',
      JIRA_USERNAME: 'your-login',
      JIRA_PASSWORD: 'your-api-token-or-password'
    }
  }
}

🔍 Client Integration Examples {#client-examples}

Node.js MCP Client

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'node',
  args: ['path/to/mcp-atlassian-ts/dist/index.js'],
  env: {
    MCP_SERVICE_MODE: 'jira',
    JIRA_URL: 'https://your-company.atlassian.net',
    JIRA_USERNAME: 'your-login',
    JIRA_PASSWORD: 'your-api-token-or-password'
  }
});

const client = new Client({
  name: 'my-app',
  version: '1.0.0'
}, {
  capabilities: {
    tools: {}
  }
});

await client.connect(transport);

Python MCP Client

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    server_params = StdioServerParameters(
        command="node",
        args=["path/to/mcp-atlassian-ts/dist/index.js"],
        env={
            "MCP_SERVICE_MODE": "jira",
            "JIRA_URL": "https://your-company.atlassian.net",
            "JIRA_USERNAME": "your-login",
            "JIRA_PASSWORD": "your-api-token-or-password"
        }
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print(f"Available tools: {tools.tools}")

asyncio.run(main())

📊 Development Features {#development-features}

Code Quality

  • TypeScript: ES2022 with strict type checking
  • ESLint: Code quality and style enforcement
  • Jest: Comprehensive testing framework
  • Hot Reload: Development server with auto-restart

Production Features

  • Caching: TTL-based with statistics (cache_stats)
  • Rate Limiting: Configurable request limits
  • Health Monitoring: Service connectivity checks (health_check)
  • Error Handling: Comprehensive error types and context
  • Logging: Structured logging with Pino

🤝 Contributing {#contributing}

  1. Fork the repository
  2. Create feature branch: git checkout -b feature/amazing-feature
  3. Commit changes: git commit -m 'Add amazing feature'
  4. Push to branch: git push origin feature/amazing-feature
  5. Open a Pull Request

📄 License {#license}

MIT License - see file for details.

🆘 Support {#support}

Built with ❤️ for the Model Context Protocol ecosystem