# 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
```bash
npm install -g leantime-mcp
```
### From source
```bash
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
```json
{
"mcpServers": {
"leantime": {
"command": "leantime-mcp",
"args": [
"https://yourworkspace.leantime.io/mcp",
"--token",
"YOUR_TOKEN_HERE"
]
}
}
}
```
#### For Local Development with Self-Signed Certificates
```json
{
"mcpServers": {
"leantime": {
"command": "leantime-mcp",
"args": [
"https://yourworkspace.leantime.io/mcp",
"--token",
"YOUR_TOKEN_HERE",
"--insecure"
]
}
}
}
```
#### Using Absolute Path
```json
{
"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
```json
{
"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
```json
{
"mcp": {
"servers": {
"leantime": {
"command": "leantime-mcp",
"args": [
"https://yourworkspace.leantime.io/mcp",
"--token",
"YOUR_TOKEN_HERE"
]
}
}
}
}
```
#### Command Line Usage
```bash
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`)
```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:
```json
{
"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
# 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
```yaml
# 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
```json
{
"name": "leantime",
"command": "leantime-mcp",
"args": [
"https://yourworkspace.leantime.io/mcp",
"--token",
"YOUR_TOKEN_HERE"
],
"env": {
"NODE_ENV": "production"
}
}
```
#### Docker Configuration
```yaml
# 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
```bash
# 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
```bash
# Staging with moderate reliability
leantime-mcp https://staging.leantime.com/mcp \
--token "staging-token-456" \
--max-retries 3 \
--retry-delay 1000
```
#### Production Environment
```bash
# 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
```bash
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
```bash
leantime-mcp https://leantime.example.com/mcp --token abc123
```
#### Using API Key authentication
```bash
leantime-mcp https://leantime.example.com/mcp --token abc123 --auth-method x-api-key
```
#### Local development with self-signed certificates
```bash
leantime-mcp https://localhost/mcp --token abc123 --insecure
```
#### Specific protocol version
```bash
leantime-mcp https://leantime.example.com/mcp --token abc123 --protocol-version 2025-03-26
```
#### High-reliability setup with custom retry settings
```bash
leantime-mcp https://leantime.example.com/mcp --token abc123 --max-retries 5 --retry-delay 2000
```
#### Disable caching for development/testing
```bash
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
```bash
# 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
```bash
# 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:
```bash
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:
```json
"command": "node",
"args": ["/absolute/path/to/leantime-mcp/dist/index.js", ...]
```
### Debug Mode
Enable verbose logging to troubleshoot connection issues:
```bash
# 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](https://github.com/leantime/leantime-mcp/issues)
- Check [Leantime documentation](https://leantime.io/docs/) 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
