Leantime MCP Bridge

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

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.

- 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

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

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

{ "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" ] } } }

{ "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" ] } } }

For Claude Code, add to yourclaude_config.jsonor use the command line:

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

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

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" ] } } }

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:

# 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() )

# 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

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

# 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

# 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 with moderate reliability leantime-mcp https://staging.leantime.com/mcp \ --token "staging-token-456" \ --max-retries 3 \ --retry-delay 1000

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

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

- <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)

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

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

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

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

- 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

- 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

- 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

- 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

- 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

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

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

# 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

# Watch for changes and rebuild npm run dev

- 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

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 tostderrto avoid interfering with MCP communication onstdout.

"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.

- 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

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: Runnpm 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", ...]

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

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

Proxy logs: All proxy logs go tostderrand include:

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

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...

MIT License - see LICENSE file for details
- 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

- Create an issue onGitHub Issues
- CheckLeantime documentationfor MCP setup
- Verify your token has proper permissions in Leantime

An MCP server for WordPress plugin audits