Leantime MCP Server

This plugin provides a Model Context Protocol (MCP) server for Leantime, allowing AI assistants and other MCP clients to interact with Leantime functionality through standardized protocols.

Features

1. Comprehensive Coverage: Exposes tickets, projects, and user management functionality
2. Multiple Transport Options: Supports both STDIO and HTTP transport protocols
3. Security Features: API key authentication, IP whitelisting, and rate limiting
4. Performance Optimized: Tool discovery caching and efficient bulk operations

Installation (Self Hosted Only)

1. Go to the Leantime App Marketplace and find the "MCP Server" App.
2. After purchasing a license enter the license key into the field in Leantime
3. Click install and enable after the installation process

Configuration

Environment Variables

Configuration is not necessary but if you would like to customize the mcp server you can use the following env variables.

# MCP Server Settings
MCP_SERVER_ENABLED=true
MCP_SERVER_HOST=127.0.0.1
MCP_SERVER_PORT=3001
MCP_TRANSPORT=stdio

# Authentication (integrates with Leantime's existing auth system)
MCP_REQUIRE_AUTH=true
MCP_REQUIRED_ROLE=editor
MCP_ALLOWED_IPS=127.0.0.1,::1

# Performance
MCP_RATE_LIMIT=100
MCP_AUTO_DISCOVER_TOOLS=true
MCP_CACHE_TOOLS=true

# Limits
MCP_MAX_EXECUTION_TIME=30
MCP_MEMORY_LIMIT=256M
MCP_MAX_RESPONSE_SIZE=10485760

Authentication Methods

The MCP server integrates with Leantime's existing authentication system:

1. Personal Access Tokens (Recommended): Use the advanced authentication plugin to get personal access tokens.
2. Standard API Keys: Use existing Leantime API keys (format: lt_{username}_{hash})

Security Configuration

Required Role: Set minimum role with MCP_REQUIRED_ROLE (default: editor)
IP Whitelist: Configure allowed IPs in MCP_ALLOWED_IPS (supports CIDR notation)
Rate Limiting: Control request frequency with MCP_RATE_LIMIT

Generating Personal Access Tokens

Go to your profile and click the "Personal Access Tokens" tab. On the following screen generate a new token and save it somewhere

Running the MCP Server

Http/Remote

Once the plugin is enabled the /mcp endpoint is available automatically and you can use https://YOURLEANTIMEURL/mcp to access the server.

STDIO

To run the stdio protocol run

php bin\leantime lt-mcp:start 

Usage Examples

For AI Assistants via HTTP

The MCP server can be used with AI assistants like Claude Desktop by configuring it in the MCP settings:

{
  "mcpServers": {
    "leantime": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://YOURLEANTIMEURL/mcp",
        "--header",
        "Authorization: Bearer YOURPERSONALACCESSTOKEN"
        ],
      "env": {
        //"NODE_TLS_REJECT_UNAUTHORIZED": "0", Optional when using self signed certificates
        }
      }
    }
  }
}

Security Considerations

• Always use HTTPS in production when using HTTP transport
• Set strong API keys and rotate them regularly
• Configure IP whitelisting appropriately for your environment
• Monitor logs for suspicious activity
• Consider using rate limiting to prevent abuse

Troubleshooting

Common Issues

1. Tools not found: Run php bin/leantime lt-mcp:discover to cache tools
2. Authentication errors: Check API key configuration and IP whitelist
3. Rate limiting: Adjust MCP_RATE_LIMIT or implement request batching
4. Memory issues: Increase MCP_MEMORY_LIMIT for large datasets

Debugging

Enable request logging:

MCP_LOG_REQUESTS=true
MCP_EXPOSE_ERRORS=true

Check logs in storage/logs/leantime-xx-xx-xx.log for detailed error information.

Performance Tips

1. Use tool discovery caching in production
2. Implement appropriate rate limiting
3. Use bulk operations when possible
4. Monitor memory usage for large result sets
5. Consider HTTP transport for high-throughput scenarios

Updated on: 25/06/2025