# Wolfpack MCP Server

[![npm](https://img.shields.io/npm/v/wolfpack-mcp)](https://www.npmjs.com/package/wolfpack-mcp)

Connect your AI assistant to Wolfpack to manage work items, track issues, update documentation, and log progress—all
through natural conversation.

## Quick Start

There are two ways to connect:

- **Claude Desktop** — Use the remote MCP server with OAuth (no API key needed)
- **Coding agents** (Claude Code, Cursor, Windsurf, etc.) — Use this npm package via stdio with an API key

### Claude Desktop (Remote MCP)

Add to your Claude Desktop config file:

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

```json
{
  "mcpServers": {
    "wolfpack": {
      "type": "url",
      "url": "https://wolfpacks.work/mcp"
    }
  }
}
```

Restart Claude Desktop. You'll be prompted to sign in with your Wolfpack account via OAuth.

### Coding Agents (stdio)

#### 1. Generate an API Key

1. Log in to [wolfpacks.work](https://wolfpacks.work)
2. Go to **Account Settings** → **API Keys**
3. Click **Create New Key**
4. Select the permissions you need (work items, issues, wiki, etc.)
5. Copy your API key immediately—you won't see it again

#### 2. Configure Your Agent

**Claude Code** (`~/.claude/settings.json` or project `.mcp.json`):

```json
{
  "mcpServers": {
    "wolfpack": {
      "command": "npx",
      "args": ["-y", "wolfpack-mcp@latest"],
      "env": {
        "WOLFPACK_API_KEY": "wfp_sk_your_api_key_here"
      }
    }
  }
}
```

**Cursor / Windsurf** — use the same `command`, `args`, and `env` in your editor's MCP configuration.

## Installation

```bash
npm install -g wolfpack-mcp
```

Or use directly with npx (no installation required):

```bash
npx wolfpack-mcp
```

**Try these prompts:**

- "What work items are assigned to me?"
- "Show me open bugs"
- "Create a work item to refactor the auth module"
- "Update issue #42 status to in-progress"
- "Add a journal entry about today's progress"

## What You Can Do

| Feature        | Example Prompts                                                                       |
| -------------- | ------------------------------------------------------------------------------------- |
| **Work Items** | "What's on my plate?" / "Create a task for API updates" / "Mark task #15 as done"     |
| **Issues**     | "Show critical bugs" / "File a bug about the login timeout" / "Assign issue #8 to me" |
| **Wiki**       | "Find docs about deployment" / "Create a page for onboarding steps"                   |
| **Journal**    | "Log my standup notes" / "What did I work on last week?"                              |
| **Radar**      | "What initiatives are in progress?" / "Show the roadmap"                              |

## Multiple Organisations

If you belong to multiple organisations, agent builder tools (agents, templates, skills, LLM models) need to know which org to operate on. You can:

- Use `list_organisations` to see your orgs
- Pass `org_slug` to any agent builder tool to target a specific org
- Or pre-select a default org with the `WOLFPACK_ORG_SLUG` environment variable:

```json
{
  "env": {
    "WOLFPACK_API_KEY": "wfp_sk_your_api_key_here",
    "WOLFPACK_ORG_SLUG": "your-org-slug"
  }
}
```

If you only belong to one organisation, this is handled automatically.

## Multiple Projects

If you belong to multiple project teams, your AI assistant will ask which team you mean, or you can specify:

- "Show my work items for the Platform team"
- Use `list_teams` to see all your teams

To pre-select a default project for coding agents, add `WOLFPACK_TEAM_SLUG` to your env config:

```json
{
  "env": {
    "WOLFPACK_API_KEY": "wfp_sk_your_api_key_here",
    "WOLFPACK_TEAM_SLUG": "your-team-slug"
  }
}
```

The MCP server is designed to work within **one project at a time**:

- The agent will identify which project you're working in before taking actions
- Once a project is identified, all operations stay within that project
- The agent will not perform bulk actions across multiple projects
- To switch projects, explicitly ask (e.g., "switch to the Platform project")

## Available Tools Reference

<details>
<summary>Click to expand full tool documentation</summary>

### Teams

#### `list_teams`

List all teams you have access to.

- **Parameters:** None
- **Returns:** Array of teams with `id`, `slug`, and `name`

### Work Items

#### `list_work_items`

Lists work items on the Kanban board or backlog (excludes completed/closed by default).

- `team_id` (optional): Filter by team
- `status` (optional): Filter by status (new, doing, review, ready, blocked, completed, pending/backlog, all)
- `assigned_to_id` (optional): Filter by assignee ("all", "me", "unassigned", or a user ID)
- `search` (optional): Text search in title and description
- `category_id` (optional): Filter by category ID, or "none" for uncategorized
- `priority` (optional): Filter by priority level (0-4)
- `radar_item_id` (optional): Filter by linked radar/initiative item
- `date_from`, `date_to` (optional): Filter by creation date (ISO format, e.g. "2025-01-01")
- `sort_by` (optional): Sort field (dateUpdated, dateCreated, priority, title)
- `sort_order` (optional): Sort direction (desc, asc)
- `limit`, `offset` (optional): Pagination

#### `get_work_item`

Get a specific work item.

- `work_item_id` (required): UUID or reference number
- `team_id` (optional): Required when using reference number

#### `create_work_item`

Create a new work item.

- `title` (required): Task title
- `description`, `status`, `priority`, `leading_user_id` (optional)

#### `update_work_progress`

Update work item description/notes.

- `work_item_id` (required): The work item ID
- `description` (required): Updated description (markdown)

#### `update_work_item_status`

Change work item status.

- `work_item_id` (required): The work item ID
- `status` (required): New status

#### `update_work_item_assignee`

Change the assignee on a work item.

- `work_item_id` (required): The work item ID
- `leading_user_id` (required): User ID to assign, or null to unassign

#### `pull_work_item`

Pull a work item from the backlog to the board (sets status to "new" and assigns to you).

- `work_item_id` (required): The work item ID
- `leading_user_id` (optional): User ID to assign (defaults to API key owner)

### Issues

#### `list_issues`

List issues (excludes closed by default).

- `team_id`, `status`, `severity`, `type`, `assigned_to_id` (optional): Filters
- `search` (optional): Text search in title and description
- `date_from`, `date_to` (optional): Filter by creation date (ISO format, e.g. "2025-01-01")
- `sort_by` (optional): Sort field (dateCreated, dateUpdated, severity, title)
- `sort_order` (optional): Sort direction (desc, asc)
- `limit`, `offset` (optional): Pagination

#### `get_issue`

Get a specific issue.

- `issue_id` (required): UUID or reference number
- `team_id` (optional): Required when using reference number

#### `create_issue`

Create a new issue. Human callers only — issues are how the people using the product report problems
they hit, so an agent files what it finds with `create_work_item` instead.

- `title` (required): Issue title
- `description`, `severity`, `type`, `assigned_to_id`, `environment`, `affected_version`, `reproducible`,
  `steps_to_reproduce`, `expected_behavior`, `actual_behavior` (optional)

#### `update_issue`

Update an existing issue.

- `issue_id` (required): The issue UUID
- `title`, `description`, `status`, `severity`, `assigned_to_id`, `closing_note` (optional)

### Wiki Pages

#### `list_wiki_pages`

List wiki pages.

- `search` (optional): Text search in title and content
- `date_from`, `date_to` (optional): Filter by last updated date (ISO format, e.g. "2025-01-01")
- `limit`, `offset` (optional): Pagination

#### `get_wiki_page`

Get a wiki page by ID or slug.

- `page_id` (required): UUID or slug (e.g., "getting-started")

#### `create_wiki_page`

Create a new wiki page.

- `slug` (required): URL path
- `title` (required): Page title
- `content` (required): Markdown content

#### `update_wiki_page`

Update an existing wiki page.

- `page_id` (required): The page UUID
- `title`, `content` (optional)

### Journal Entries

#### `list_journal_entries`

List journal entries.

- `search` (optional): Text search in title and content
- `date_from`, `date_to` (optional): Filter by entry date (ISO format, e.g. "2025-01-01")
- `limit`, `offset` (optional): Pagination

#### `get_journal_entry`

Get a specific journal entry.

- `entry_id` (required): UUID or reference number
- `team_id` (optional): Required when using reference number

#### `create_journal_entry`

Create a new journal entry.

- `title` (required): Entry title
- `content` (required): Markdown content
- `date` (optional): ISO date string

#### `update_journal_entry`

Update an existing journal entry.

- `entry_id` (required): The entry UUID
- `title`, `content` (optional)

### Ideas (the Idea Factory)

Offered to a key holding `mcp:ideas:read` on a project where the `idea-factory` feature is
switched on. There is no archive tool: archiving is the Idea Factory's delete, and MCP does not
surface deletes.

#### `list_ideas`

List the live ideas in a project. Each carries a stage and a boost count, and the response says
whether your own boost for today in that project is already spent.

- `sort` (optional): `popular` (default), `updated` or `newest`
- `limit`, `offset` (optional): Pagination

#### `get_idea`

Get a single idea, with its tags and the reference numbers of any work items being built from it.

- `idea_id` (required): The idea refId (number)

#### `create_idea`

Raise a new idea. It starts at the `spark` stage with no boosts.

- `title` (required): Idea title
- `content` (required): Markdown content

#### `update_idea`

Update an idea, or move it to another stage.

- `idea_id` (required): The idea refId (number)
- `title`, `content` (optional)
- `stage` (optional): `spark`, `exploring`, `building`, `shipped` or `parked`

#### `boost_idea`

Vote for an idea by spending your boost. One boost per project per day, whichever idea you spend
it on — spending it again the same day is refused rather than counted. Takes `mcp:ideas:boost`,
which is separate from `mcp:ideas:update`: voting is participation, not editing.

- `idea_id` (required): The idea refId (number)

### Comments

#### `list_work_item_comments`

List all comments on a work item.

- `work_item_id` (required): The work item UUID

#### `list_issue_comments`

List all comments on an issue.

- `issue_id` (required): The issue UUID

#### `create_work_item_comment`

Add a comment to a work item.

- `work_item_id` (required): The work item UUID
- `content` (required): Markdown content

#### `create_issue_comment`

Add a comment to an issue.

- `issue_id` (required): The issue UUID
- `content` (required): Markdown content

### Radar Items

#### `list_radar_items`

List radar items/initiatives (excludes completed by default).

- `team_id` (optional): Filter by team
- `stage` (optional): Filter by stage (pending, now, next, later, completed)
- `search` (optional): Text search in title and description
- `limit`, `offset` (optional): Pagination

#### `get_radar_item`

Get a specific radar item.

- `item_id` (required): UUID or reference number
- `team_id` (optional): Required when using reference number

### Tags

Tags label work items, issues, wiki pages and journal entries, and are filed under nestable groups. Project admins define them; a key with `mcp:tags:manage` lets an admin's agent keep them in step with an external system (for example, one tag per CRM customer account keyed on `external_id`). There is no delete tool — archive instead (`update_tag` with `archived: true`); removing a tag outright is done in the browser.

#### `list_tags`

List a project's tags with id, name, colour, `externalId`, the group each is filed under and whether it is `archived`. Any key that can read a tagged module may list them.

- `project_slug` (optional): Project slug

#### `create_tag`

- `name` (required): Tag name, unique within the project
- `colour` (optional): Hex colour such as `#e879f9`
- `group` (optional): Tag group name or id
- `external_id` (optional): Id of this tag in the system that maintains it, unique within the project
- `project_slug` (optional): Project slug

#### `update_tag`

Only the fields given change; pass `null` for `colour`, `group` or `external_id` to clear it. `archived: true` is the soft delete: the tag stays on the items that carry it and keeps its page, but no picker offers it and it cannot be applied; `archived: false` restores it. A sync uses this for accounts the source system has dropped.

- `tag` (required): Tag id or current name
- `name`, `colour`, `group`, `external_id`, `archived` (optional)
- `project_slug` (optional): Project slug

#### `list_tag_groups`

List a project's tag groups with their parent and full path (e.g. `Customers › EMEA`).

- `project_slug` (optional): Project slug

#### `create_tag_group`

- `name` (required): Group name, unique within the project
- `parent` (optional): Parent group name or id
- `project_slug` (optional): Project slug

#### `update_tag_group`

- `group` (required): Group id or current name
- `name` (optional): New name
- `parent` (optional): Parent group name or id, or `null` for the top level
- `project_slug` (optional): Project slug

### Images

#### `upload_image`

Upload an image file from disk and get back a permanent URL for use in markdown content.

- `file_path` (required): Absolute path to an image file (JPEG, PNG, GIF, WebP; max 5MB)
- `team_id` (optional): Team ID (required for multi-team users)

#### `download_image`

Download and view an image referenced in content fields. Content from work items, issues, wiki pages, journal entries, and comments may contain image references like `![alt](/api/files/images/...)`. Use this tool with that URL path to view the image.

- `image_url` (required): The image URL path (e.g. `/api/files/images/{team}/{filename}`)

</details>