Pilea MCP Server

A Model Context Protocol (MCP) server that connects your AI coding assistant to Pilea, enabling seamless backlog-to-code workflows with full customer context.

Features

• Backlog management — list, select, create, and update backlog items
• Customer insights — view customer profiles, their feedback, and linked backlog items
• Mentions — browse and create customer feedback (mentions)
• Tags — organize items with tags
• Workspaces — switch between workspaces by name
• Git integration — commit message suggestions with automatic Pilea tracking
• Search — search across all backlog items and mentions

Prerequisites

• Node.js 18+
• Git (for commit tracking features)
• Pilea API key

Installation

npm install -g @pilea-insights/mcp

Configuration

Add the server to your MCP client configuration:

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pilea": {
      "command": "npx",
      "args": ["@pilea-insights/mcp"],
      "env": {
        "PILEA_API_KEY": "your_api_key_here",
        "PILEA_API_BASE_URL": "https://api.getpilea.com/api/v1"
      }
    }
  }
}

Claude Code

Edit ~/.config/claude/mcp.json:

{
  "mcpServers": {
    "pilea": {
      "command": "npx",
      "args": ["@pilea-insights/mcp"],
      "env": {
        "PILEA_API_KEY": "your_api_key_here",
        "PILEA_API_BASE_URL": "https://api.getpilea.com/api/v1"
      }
    }
  }
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | PILEA_API_KEY | Yes | Your Pilea API key (organization-level, passed via X-Api-Key header) | | PILEA_API_BASE_URL | Yes | The Pilea API base URL (e.g. https://api.getpilea.com/api/v1) | | PILEA_WORKSPACE_ID | No | Target a specific workspace by public ID (e.g. ws_abc123), or all for every workspace. Omit to use org default. Can also be set at runtime via pilea_set_workspace. |

Available Tools

Backlog Items

| Tool | Description | |------|-------------| | pilea_list_backlog_items | List backlog items with optional filters (triage status, analysis unit) | | pilea_select_item | Select an item by index to load full context | | pilea_open_item | Open an item by URL or ID | | pilea_create_item | Create a new backlog item | | pilea_create_from_chat | Create a backlog item from conversation context | | pilea_update_item_status | Update triage status (New, Saved, Ready for dev, In progress, Completed, Archived, Snoozed) | | pilea_delete_backlog_item | Delete a backlog item by ID | | pilea_finalize_item | Mark item as completed with git commit hash | | pilea_search_items | Search all items and their mentions |

Customers

| Tool | Description | |------|-------------| | pilea_list_customers | List all customers | | pilea_create_customer | Create a new customer | | pilea_update_customer | Update a customer by ID | | pilea_delete_customer | Delete a customer by ID | | pilea_get_customer_insights | Get a customer's mentions and linked backlog items (by name) |

Mentions

| Tool | Description | |------|-------------| | pilea_list_mentions | List all mentions (customer feedback) | | pilea_get_mention | Get a single mention by ID | | pilea_get_item_mentions | Get mentions linked to a specific backlog item | | pilea_create_mention | Create a new mention with optional customer linking | | pilea_bulk_create_mentions | Bulk create multiple mentions at once | | pilea_delete_mention | Delete a mention by ID | | pilea_add_mention_attachments | Add attachments to an existing mention |

Tags

| Tool | Description | |------|-------------| | pilea_list_tags | List all tags with mention counts | | pilea_get_tag | Get a single tag by ID | | pilea_create_tag | Create a new tag | | pilea_update_tag | Update a tag by ID | | pilea_delete_tag | Delete a tag by ID |

Workspaces

| Tool | Description | |------|-------------| | pilea_list_workspaces | List available workspaces | | pilea_set_workspace | Switch workspace by name (supports "all" and "default") |

Git Integration

| Tool | Description | |------|-------------| | pilea_commit_hint | Get commit message suggestions for the active item | | pilea_install_git_hook | Install a git hook that auto-appends the Pilea item ID to commits |

Example Workflow

> Show me backlog items from Pilea

[1] Implement dark mode (New)
[2] Filter settings not applied (Ready for dev)
[3] Export to CSV (In progress)

> I'll work on number 2

Selected Item: Filter settings not applied
Product Area: Dashboard
URL: https://app.getpilea.com/backlog/abc123
...

> Show me the customer feedback for this

Found 3 mention(s) for backlog item abc123:
1. Support ticket (intercom): Users report filters reset after page reload...
2. Feature request (slack): Would be great if filters persisted...
...

> [fix the bug]

> Give me a commit message

Title: fix: Filter settings not applied
Footer: Pilea: abc123

> Mark this as completed

Item finalized!
Item: Filter settings not applied
Commit: def456
Status: Completed

Testing with MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

Add PILEA_API_KEY and PILEA_API_BASE_URL in the Environment Variables section, then click Connect.

Development

git clone https://github.com/Pilea-Insights/pilea-mcp-poc.git
cd pilea-mcp-poc
npm install
npm run build
npm run dev    # watch mode

Publishing

npm login
npm version patch  # or minor/major
npm run build
npm publish
git push --follow-tags

License

MIT