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

Method	Header Format	Example
`Bearer` (default)	`Authorization: Bearer <token>`	`--auth-method Bearer`
`X-API-Key`	`X-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

Protocol Handling: Uses official MCP SDK for robust JSON-RPC message handling
Authentication: Adds appropriate authentication headers based on chosen method
Transport Layer: Supports both regular HTTP responses and Server-Sent Events (SSE)
Error Handling: Comprehensive error handling with proper JSON-RPC error responses
Session Management: Tracks MCP session IDs for stateful interactions
Retry Logic: Exponential backoff with jitter prevents thundering herd problems
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

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes with TypeScript
Add tests if applicable
Build and test (npm run build && npm test)
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

Leantime MCP Bridge

Leantime MCP Bridge

✨ Features

Pre-Requisites

🚀 Installation

From npm

From source

📖 Usage

🖥️ Claude Desktop Configuration

Basic Configuration

For Local Development with Self-Signed Certificates

Using Absolute Path

Production Configuration with Enhanced Security

💻 Claude Code Configuration

Configuration File

Command Line Usage

🎯 Cursor Configuration

Workspace Settings (.vscode/settings.json)

Global Settings

🤖 OpenAI/ChatGPT Custom GPT Configuration

OpenAI API Configuration

Custom GPT Actions Configuration

🌐 Universal MCP Client Configuration

Standard MCP Configuration

Docker Configuration

📱 Environment-Specific Examples

Development Environment

Staging Environment

Production Environment

🔧 Command Line Usage

Parameters

Authentication Methods

Examples

Basic usage with Bearer token

Using API Key authentication

Local development with self-signed certificates

Specific protocol version

High-reliability setup with custom retry settings

Disable caching for development/testing

🔧 How It Works

🔄 Advanced Features

Retry Logic with Exponential Backoff

Smart Response Caching

Production-Ready Reliability

🏗️ Architecture

v2.0 Improvements over v1.x

Protocol Support

🧪 Development

Prerequisites

Building from Source

Development Mode

🛡️ Security Considerations

🐛 Error Handling

🛠️ Troubleshooting

Common Issues and Solutions

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

"Invalid JSON-RPC response" errors in Claude Desktop

Connection keeps dropping/restarting

Proxy exits immediately without error

"Command not found: leantime-mcp"

Debug Mode

Checking Logs

📊 Logging

📄 License

🤝 Contributing

💬 Support

📋 Changelog

1.6.0 (Latest)

1.x.x (Legacy)

Related Servers

Gamma MCP Server

Outlook Meetings Scheduler

Video Editor MCP Server

Umbraco MCP

PapersGPT for Zotero

Odoo

Gezhe PPT

Todoist

Coda

Spotify

Workspace Settings (`.vscode/settings.json`)