Leantime MCP Bridge

An MCP proxy bridge for the Leantime project management system, forwarding JSON-RPC messages with proper authentication.

View on GitHub →

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

🚀 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

MethodHeader FormatExample
Bearer (default)Authorization: Bearer <token>--auth-method Bearer
X-API-KeyX-API-Key: <token>--auth-method X-API-Key

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 x-api-key

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:

📋 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

Related Servers