> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://support.leantime.io/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Leantime MCP Server

||| The MCP Server plugin is still in beta and may include bugs. If you find a bug please [submit an issue here](https://github.com/Leantime/leantime/issues)

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

|| Note: Standard Leantime API Keys are service accounts and not tied to any account. Prompts like "What are my tasks for today..." will not work correctly. Instead use Personal Access Tokens that you can get via the [Advanced Auth Plugin](https://marketplace.leantime.io/product/advanced-auth/) when self hosted.


### 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
|| Available of v0.9.2 

```
"mcpServers": {
        "leantime": {
          "command": "php",
          "args": [
            "/path-to-leantime/bin/leantime",
            "lt-mcp:start",
            "--transport=stdio",
            "--token=YOUR_TOKEN"
          ]
        }
      },
```

## Usage Examples

| To connect to a remote MCP server you need a MCP Poxy which is a small program that funnels requests to your server. We have a simple mcp proxy available as [npm package](https://www.npmjs.com/package/leantime-mcp). You are free to use other proxies that support Bearer Token Authentication. 

To install the leantime bridge run: npm install -g leantime-mcp

### For AI Assistants via HTTP

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

*Using leantime-mcp (*[leantme-mcp docs](https://www.npmjs.com/package/leantime-mcp)*)*

```
{
  "mcpServers": {
    "leantime": {
      "command": "leantime-mcp",
      "args": [
        "https://YOURLEANTIMEURL/mcp",
        "--token",
        "YOUR_TOKEN",
      ]
    }
  }
}
```

*Using MCP-Remote*

```json
{
  "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:

```env
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