LunaTask MCP Server

LunaTask MCP Server

LunaTask MCP is an unofficial Model Context Protocol server that provides a standardized bridge between AI models and the LunaTask API. It's designed as a lightweight, asynchronous Python application using the FastMCP framework, running as a local subprocess to enable AI tools to interact with LunaTask data.

Important Notes

End-to-End Encryption

LunaTask uses end-to-end encryption for sensitive task and note data. As a result:

• Task name/note fields and note content are not included in API responses
• Only non-sensitive metadata and structural information is available
• This is a security feature of LunaTask and cannot be bypassed
• The name, note, and content fields can be included in create requests
• LunaTask automatically encrypts these fields client-side before storage
• Once created, these fields will not be visible in GET responses due to E2E encryption
• This is normal LunaTask behavior and ensures data privacy

Task IDs

• Task IDs are unique identifiers assigned by LunaTask
• Use the All Tasks resource to discover available task IDs
• Task IDs remain consistent across API calls

Rate Limiting

• The server implements rate limiting to prevent API abuse
• If you encounter rate limit errors, wait before retrying
• Rate limits are per-server instance and reset over time

Local Installation

Lunatask MCP Server is managed by uv, so you will need to install it.

Using `uv`

# Install dependencies and create the local virtual environment
uv sync

# Optionally verify the package imports correctly
uv run python -c "import lunatask_mcp"

Server Configuration

The LunaTask MCP server supports flexible configuration through TOML files and command-line arguments. A bearer token is required to authenticate with the LunaTask API.

Quick Start

1. Copy the example configuration file to a path you prefer:

cp config.example.toml ~/path/to/your/lunatask_mcp_config.toml

2. Edit the copied configuration file and add your LunaTask API bearer token:

lunatask_bearer_token = "your_lunatask_bearer_token_here"

3. Run the server:

uv run lunatask-mcp --config-file /path/to/your/config.toml

Note: To create an access token open LunaTask app, open application settings, head to "Access tokens" section, and create a new access token. Then, click "Copy to clipboard", and paste it in the lunatask_bearer_token field in the config file.

Configuration Methods

The server supports three configuration methods with the following precedence (highest to lowest):

1. Command-line arguments (highest priority)
2. Configuration file (TOML format)
3. Default values (lowest priority)

Command-Line Usage

# Basic usage with default config file (./config.toml)
uv run lunatask-mcp

# Specify a custom config file
uv run lunatask-mcp --config-file /path/to/your/config.toml

# Override specific settings (examples)
uv run lunatask-mcp --log-level DEBUG --port 9000
uv run lunatask-mcp --base-url https://api.lunatask.app/v1/
uv run lunatask-mcp --token "$LUNATASK_TOKEN"
uv run lunatask-mcp --rate-limit-rpm 120 --rate-limit-burst 20

# Get help on available options
uv run lunatask-mcp --help

Configuration File Format

Create a config.toml file with your settings:

# Required: Your LunaTask API bearer token
lunatask_bearer_token = "your_lunatask_bearer_token_here"

# Optional: API base URL (default: https://api.lunatask.app/v1/)
lunatask_base_url = "https://api.lunatask.app/v1/"

# Optional: Port for future HTTP transport (default: 8080, range: 1-65535)
# Note: Currently unused as server only supports stdio transport
port = 8080

# Optional: Logging level (default: INFO)
# Valid values: DEBUG, INFO, WARNING, ERROR, CRITICAL
log_level = "INFO"

# Optional: Connectivity test during startup (default: false)
test_connectivity_on_startup = false

# Optional: Rate limiting (defaults: rpm=60, burst=10)
rate_limit_rpm = 60
rate_limit_burst = 10

# Optional: HTTP client tuning
# Number of additional retry attempts for transient failures (default: 2)
http_retries = 2
# Initial retry backoff delay in seconds; doubles with each retry (default: 0.25)
http_backoff_start_seconds = 0.25
# Minimum delay before mutating requests (POST/PATCH/DELETE); set to 0.0 to disable (default: 0.0)
http_min_mutation_interval_seconds = 0.0
# Custom User-Agent header advertised to the LunaTask API
http_user_agent = "lunatask-mcp/0.2.1"
# Timeout in seconds for establishing the TLS connection
timeout_connect = 5.0
# Timeout in seconds for reading the response body
timeout_read = 30.0

Configuration Discovery

• If --config-file is not specified, the server looks for ./config.toml
• Missing configuration files are only an error if explicitly specified
• Default values are used when no configuration file exists

Configuration Validation

The serv