npm package: @pilea-insights/mcp
Description: MCP server for Pilea — manage backlog items, customer feedback, mentions, tags, and workspaces from your AI coding assistant
Latest version: 0.2.2

# Pilea MCP Server

A Model Context Protocol (MCP) server that connects your AI coding assistant to [Pilea](https://getpilea.com), 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

```bash
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`:

```json
{
  "mcpServers": {
    "pilea": {
      "command": "npx",
      "args": ["@pilea-insights/mcp"],
      "env": {
        "PILEA_API_KEY": "your_api_key_here",
        "PILEA_API_BASE_URL": "https://pilea-api-22ncm33v4q-ew.a.run.app/api/v1"
      }
    }
  }
}
```

### Claude Code

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

```json
{
  "mcpServers": {
    "pilea": {
      "command": "npx",
      "args": ["@pilea-insights/mcp"],
      "env": {
        "PILEA_API_KEY": "your_api_key_here",
        "PILEA_API_BASE_URL": "https://pilea-api-22ncm33v4q-ew.a.run.app/api/v1"
      }
    }
  }
}
```

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `PILEA_API_KEY` | Yes | Your Pilea API key |
| `PILEA_API_BASE_URL` | Yes | The Pilea API base URL |
| `PILEA_WORKSPACE_ID` | No | Target a specific workspace (or use `pilea_set_workspace` at runtime) |

## 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_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_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_item_mentions` | Get mentions linked to a specific backlog item |
| `pilea_create_mention` | Create a new mention with optional customer linking |

### Tags

| Tool | Description |
|------|-------------|
| `pilea_list_tags` | List all tags with mention counts |
| `pilea_create_tag` | Create a new tag |

### 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

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

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

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

## License

MIT