elean MCP

Model Context Protocol server for the Elean task management API.

Connect AI assistants (Claude, Cursor, etc.) directly to your Elean workspace. Create, search, update, and manage tasks through natural language.

Requirements

• Node.js 18 or later
• An Elean API key (created in Workspace Settings → API Keys)

Usage

Run directly with npx — no installation required:

npx @stripsior/elean --key el_yourkey --project your-project-slug

| Flag | Alias | Description | |---|---|---| | --key | -k | Your Elean API key (starts with el_) | | --project | -p | Project slug from the project URL | | --help | -h | Show usage |

Claude Desktop setup

Add this to your Claude Desktop MCP configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "elean": {
      "command": "npx",
      "args": ["@stripsior/elean", "--key", "el_yourkey", "--project", "your-project-slug"]
    }
  }
}

Restart Claude Desktop after saving. You should see the Elean tools available in the tool picker.

Available tools

| Tool | Description | Required scope | |---|---|---| | list_statuses | List all custom task statuses in the project | task:read | | list_tasks | List tasks with pagination and filters | task:read | | get_task | Get full details of a single task by ID | task:read | | create_task | Create a new task | task:create | | update_task | Update one or more fields of an existing task | task:update | | delete_task | Permanently delete a task | task:update | | list_comments | List all comments on a task | task:read | | add_comment | Add a comment to a task | task:update | | get_attachment_url | Get a download URL for a file attachment | task:read | | upload_attachment | Upload a file to a task (max 10 MB, base64) | task:create |

Make sure your API key has the scopes required for the operations you want to use.

API keys

API keys are managed in Workspace Settings → API Keys. Each key has:

• Scopes — task:read, task:create, task:update
• Project scope — all projects or a specific one
• Expiry — optional expiration date

Keys are shown once at creation time. Store yours securely.

Development

# Install dependencies
npm install

# Build
npm run build

# Type-check without building
npm run typecheck

# Run from source (no build step)
npm run dev -- --key el_yourkey --project your-slug

Project structure

src/
├── index.ts        # CLI entry point and MCP server bootstrap
├── client.ts       # Typed Elean HTTP client
├── types.ts        # Zod schemas and inferred TypeScript types
└── tools/
    ├── index.ts        # Tool registration aggregator
    ├── statuses.ts     # list_statuses
    ├── tasks.ts        # list_tasks, get_task, create_task, update_task, delete_task
    ├── comments.ts     # list_comments, add_comment
    └── attachments.ts  # get_attachment_url, upload_attachment

Inspect tools locally

Use the MCP inspector to browse tools and call them interactively:

npx @modelcontextprotocol/inspector dist/index.js -- --key el_yourkey --project your-slug

License

MIT