Leantime/leantime-mcp

Leantime MCP Bridge

A robust Model Context Protocol (MCP) proxy bridge for Leantime project management system. Built with TypeScript and the official MCP SDK, this tool provides a reliable bridge between MCP clients and Leantime servers.

✨ Features

• Built with Official MCP SDK: Uses @modelcontextprotocol/sdk for robust protocol handling
• Multiple Authentication Methods: Bearer, API Key, Token, and X-API-Key headers
• Protocol Version Support: MCP 2025-03-26 (latest) with backward compatibility
• Advanced Transport Support: HTTP/HTTPS, Server-Sent Events (SSE), and streaming responses
• TypeScript Implementation: Type-safe, maintainable codebase

Pre-Requisites

• If you are self hosted, you need the MCPServer Plugin https://marketplace.leantime.io/product/mcp-server/
• Personal access token (or api-key) generated through the Leantime UI

🚀 Installation

From npm

npm install -g leantime-mcp

From source

git clone https://github.com/leantime/leantime-mcp.git
cd leantime-mcp
npm install
npm run build
npm install -g .

📖 Usage

🖥️ Claude Desktop Configuration

Add to your claude_desktop_config.json:

Basic Configuration

{
  "mcpServers": {
    "leantime": {
      "command": "leantime-mcp",
      "args": [
        "https://yourworkspace.leantime.io/mcp",
        "--token",
        "YOUR_TOKEN_HERE"
      ]
    }
  }
}

For Local Development with Self-Signed Certificates

{
  "mcpServers": {
    "leantime": {
      "command": "leantime-mcp",
      "args": [
        "https://yourworkspace.leantime.io/mcp",
        "--token",
        "YOUR_TOKEN_HERE",
        "--insecure"
      ]
    }
  }
}

Using Absolute Path

{
  "mcpServers": {
    "leantime": {
      "command": "node",
      "args": [
        "/path/to/leantime-mcp/dist/index.js",
        "https://your-leantime.com/mcp",
        "--token",
        "YOUR_TOKEN_HERE"
      ]
    }
  }
}

Production Configuration with Enhanced Security

{
  "mcpServers": {
    "leantime": {
      "command": "leantime-mcp",
      "args": [
        "https://yourworkspace.leantime.io/mcp",
        "--token",
        "YOUR_TOKEN_HERE",
        "--auth-method",
        "Bearer",
        "--max-retries",
        "5",
        "--retry-delay",
        "2000"
      ]
    }
  }
}

💻 Claude Code Configuration

For Claude Code, add to your claude_config.json or use the command line:

Configuration File

{
  "mcp": {
    "servers": {
      "leantime": {
        "command": "leantime-mcp",
        "args": [
          "https://yourworkspace.leantime.io/mcp",
          "--token",
          "YOUR_TOKEN_HERE"
        ]
      }
    }
  }
}

Command Line Usage

claude --mcp-server leantime="leantime-mcp https://your-leantime.com/mcp --token YOUR_TOKEN_HERE"

🎯 Cursor Configuration

For Cursor IDE, add to your workspace settings or global settings:

Workspace Settings (.vscode/settings.json)

{
  "mcp.servers": {
    "leantime": {
      "command": "leantime-mcp",
      "args": [
        "https://yourworkspace.leantime.io/mcp",
        "--token",
        "YOUR_TOKEN_HERE"
      ]
    }
  }
}

Global Settings

Open Cursor Settings → Extensions → MCP and add:

{
  "leantime": {
    "command": "leantime-mcp",
    "args": [
      "https://yourworkspace.leantime.io/mcp",
      "--token",
      "YOUR_TOKEN_HERE"
    ]
  }
}

🤖 OpenAI/ChatGPT Custom GPT Configuration

For ChatGPT with MCP support or OpenAI API integration:

OpenAI API Configuration

# Python example using OpenAI with MCP
import openai
from mcp_client import MCPClient

# Initialize MCP client
mcp_client = MCPClient(
    command="leantime-mcp",
    args=[
        "https://yourworkspace.leantime.io/mcp",
        "--token",
        "YOUR_TOKEN_HERE"
    ]
)

# Use with OpenAI
client = openai.OpenAI(api_key="your-openai-key")
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Show me my Leantime projects"}],
    tools=mcp_client.get_tools()
)

Custom GPT Actions Configuration

# For Custom GPT Actions
openapi: 3.0.0
info:
  title: Leantime MCP Proxy
  version: 2.0.0
servers:
  - url: https://yourworkspace.leantime.io/mcp
paths:
  /tools/list:
    post:
      summary: List available tools
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                jsonrpc:
                  type: string
                  default: "2.0"
                method:
                  type: string
                  default: "tools/list"
                id:
                  type: integer
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

🌐 Universal MCP Client Configuration

For any MCP-compatible client:

Standard MCP Configuration

{
  "name": "leantime",
  "command": "leantime-mcp",
  "args": [
    "https://yourworkspace.leantime.io/mcp",
    "--token",
    "YOUR_TOKEN_HERE"
  ],
  "env": {
    "NODE_ENV": "production"
  }
}

Docker Configuration

# docker-compose.yml
version: '3.8'
services:
  leantime-mcp:
    image: node:18-alpine
    command: npx leantime-mcp https://yourworkspace.leantime.io/mcp --token YOUR_TOKEN_HERE
    environment:
      - NODE_ENV=production
    volumes:
      - ./config:/config
    stdin_open: true
    tty: true

📱 Environment-Specific Examples

Development Environment

# Local testing with debug logging
leantime-mcp https://localhost:8080/mcp \
  --token "dev-token-123" \
  --insecure \
  --no-cache \
  --max-retries 1 \
  2>debug.log

Staging Environment

# Staging with moderate reliability
leantime-mcp https://staging.leantime.com/mcp \
  --token "staging-token-456" \
  --max-retries 3 \
  --retry-delay 1000

Production Environment

# Production with high reliability
leantime-mcp https://leantime.company.com/mcp \
  --token "prod-token-789" \
  --auth-method Bearer \
  --max-retries 5 \
  --retry-delay 2000

🔧 Command Line Usage

leantime-mcp <url> --token <token> [options]

Parameters

• <url> - The Leantime MCP endpoint URL (required)
• --token <token> - Authentication token (required)
• --auth-method <method> - Authentication method (optional, default: Bearer)
• --insecure - Skip SSL certificate verification (optional)
• --protocol-version <version> - MCP protocol version (optional)
• --max-retries <num> - Maximum retry attempts (optional, default: 3)
• --retry-delay <ms> - Base retry delay in milliseconds (optional, default: 1000)
• --no-cache - Disable response caching (optional)

Authentication Methods

Examples

Basic usage with Bearer token

leantime-mcp https://leantime.example.com/mcp --token abc123

Using API Key authentication

leantime-mcp https://leantime.example.com/mcp --token abc123 --auth-method ApiKey

Local development with self-signed certificates

leantime-mcp https://localhost/mcp --token abc123 --insecure

Specific protocol version

leantime-mcp https://leantime.example.com/mcp --token abc123 --protocol-version 2025-03-26

High-reliability setup with custom retry settings

leantime-mcp https://leantime.example.com/mcp --token abc123 --max-retries 5 --retry-delay 2000

Disable caching for development/testing

leantime-mcp https://leantime.example.com/mcp --token abc123 --no-cache

🔧 How It Works

1. Protocol Handling: Uses official MCP SDK for robust JSON-RPC message handling
2. Authentication: Adds appropriate authentication headers based on chosen method
3. Transport Layer: Supports both regular HTTP responses and Server-Sent Events (SSE)
4. Error Handling: Comprehensive error handling with proper JSON-RPC error responses
5. Session Management: Tracks MCP session IDs for stateful interactions
6. Retry Logic: Exponential backoff with jitter prevents thundering herd problems
7. Smart Caching: Caches tool/resource/prompt lists to reduce server load

🔄 Advanced Features

Retry Logic with Exponential Backoff

• Automatic retries: Failed requests are automatically retried (default: 3 attempts)
• Exponential backoff: Delay doubles with each retry (1s → 2s → 4s...)
• Jitter: Random ±25% variation prevents thundering herd effect
• Configurable: Customize max retries and base delay via CLI options

Smart Response Caching

• Automatic caching: tools/list, resources/list, and prompts/list responses are cached
• TTL-based expiry: Cached responses expire after 5 minutes
• Memory efficient: Automatic cleanup of expired cache entries
• Configurable: Use --no-cache to disable for development/testing

Production-Ready Reliability

• Connection resilience: Handles network interruptions gracefully
• Request tracking: Numbered requests for easy debugging
• Comprehensive logging: Detailed logs to stderr (won't interfere with MCP communication)
• Graceful shutdown: Clean termination on SIGINT/SIGTERM

🏗️ Architecture

v2.0 Improvements over v1.x

• TypeScript Rewrite: Type-safe implementation with better maintainability
• Official SDK Integration: Uses @modelcontextprotocol/sdk instead of custom implementation
• Enhanced Authentication: Support for multiple authentication methods
• Better Error Handling: Proper JSON-RPC error responses and logging
• Protocol Negotiation: Automatic protocol version negotiation
• Streaming Support: Full support for SSE and streaming responses

Protocol Support

• Primary: MCP 2025-03-26 (latest specification)
• Fallback: MCP 2024-11-05 (backward compatibility)
• Auto-negotiation: Automatically detects and uses appropriate protocol version

🧪 Development

Prerequisites

• Node.js 18.0.0 or higher
• TypeScript 5.4.0 or higher
• Access to a Leantime instance with MCP support

Building from Source

# Clone the repository
git clone https://github.com/leantime/leantime-mcp.git
cd leantime-mcp

# Install dependencies
npm install

# Build TypeScript
npm run build

# Test locally
echo '{"jsonrpc":"2.0","id":1,"method":"ping"}' | node dist/index.js https://your-leantime.com/mcp --token your-token

Development Mode

# Watch for changes and rebuild
npm run dev

🛡️ Security Considerations

• HTTPS Only: Always use HTTPS in production environments
• Token Security: Store tokens securely and avoid logging them
• SSL Verification: Only use --insecure flag in development
• Token Rotation: Consider implementing token rotation for long-running processes
• Network Security: Ensure proper network security between proxy and Leantime server

🐛 Error Handling

The proxy includes comprehensive error handling for:

• Network Issues: Connection timeouts, DNS resolution failures
• Authentication: Invalid tokens, expired credentials
• Protocol Errors: Malformed JSON-RPC messages, protocol mismatches
• Server Errors: HTTP errors, invalid responses from Leantime
• Transport Issues: SSE connection problems, streaming errors

All error messages are logged to stderr to avoid interfering with MCP communication on stdout.

🛠️ Troubleshooting

Common Issues and Solutions

"Mcp-Session-Id header required for POST requests"

Fixed in v2.0: The proxy now automatically captures and includes the MCP session ID in all requests after the initial handshake.

"Invalid JSON-RPC response" errors in Claude Desktop

Fixed in v2.0: The proxy now converts PHP error responses from Leantime into proper JSON-RPC error format that Claude Desktop can understand.

Connection keeps dropping/restarting

• Check your token: Ensure the Leantime API token is valid and has proper permissions
• Network issues: Use --max-retries 5 for unreliable connections
• SSL problems: Use --insecure for development with self-signed certificates

Proxy exits immediately without error

This is normal behavior - the proxy waits for JSON-RPC messages from Claude Desktop via stdin. If you're testing manually, send a JSON-RPC message:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | leantime-mcp https://your-leantime.com/mcp --token YOUR_TOKEN

"Command not found: leantime-mcp"

• Global install: Run npm install -g . from the project directory
• Use absolute path: Reference the compiled script directly in your Claude Desktop config:

  "command": "node",
  "args": ["/absolute/path/to/leantime-mcp/dist/index.js", ...]
  

Debug Mode

Enable verbose logging to troubleshoot connection issues:

# The proxy logs to stderr, so you can see debug info while MCP communication continues
leantime-mcp https://your-leantime.com/mcp --token YOUR_TOKEN 2>debug.log

Checking Logs

Claude Desktop logs: Check ~/Library/Logs/Claude/mcp-server-leantime.log (macOS) for detailed MCP communication logs.

Proxy logs: All proxy logs go to stderr and include:

• Request/response tracking with numbered IDs
• Cache hit/miss information
• Retry attempts and backoff timing
• Session ID management
• Error details and conversions

📊 Logging

The proxy provides detailed logging for debugging:

[LeantimeMCP] Initializing Leantime MCP Proxy...
[LeantimeMCP] Server: https://leantime.example.com/mcp
[LeantimeMCP] Auth Method: Bearer
[LeantimeMCP] SSL verification: enabled
[LeantimeMCP] Protocol version: 2025-03-26
[LeantimeMCP] Ready to handle MCP requests...

📄 License

MIT License - see LICENSE file for details

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with TypeScript
4. Add tests if applicable
5. Build and test (npm run build && npm test)
6. Submit a pull request

💬 Support

For issues and questions:

• Create an issue on GitHub Issues
• Check Leantime documentation for MCP setup
• Verify your token has proper permissions in Leantime

📋 Changelog

1.6.0 (Latest)

• 🎉 Complete TypeScript rewrite using official MCP SDK
• ✨ Multiple authentication methods (Bearer, ApiKey, Token, X-API-Key)
• 🚀 Enhanced protocol support (MCP 2025-03-26 + backward compatibility)
• 🔧 Improved error handling and logging
• 📡 Better transport layer with SSE and streaming support
• 🛡️ Enhanced security and session management
• 📦 Smaller codebase (80% reduction) with better maintainability
• 🔄 Advanced retry logic with exponential backoff and jitter
• 💾 Smart caching for tool lists and schemas (5-minute TTL)
• ⚡ Production-ready connection resilience and error recovery

1.x.x (Legacy)

• Basic MCP proxy functionality
• HTTP/HTTPS support
• Bearer token authentication only
• SSL verification bypass option