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/sdkfor 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, andprompts/listresponses are cached - TTL-based expiry: Cached responses expire after 5 minutes
- Memory efficient: Automatic cleanup of expired cache entries
- Configurable: Use
--no-cacheto 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/sdkinstead 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
--insecureflag 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 5for unreliable connections - SSL problems: Use
--insecurefor 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