# beans-mcp [Health: Active]

**Category:** 📋 Product Management  
**Repository:** https://github.com/selfagency/beans-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 209  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/beans-mcp

## Description
Interact with the Beans CLI issue tracker agentically

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "beans-mcp": {
    "command": "npx",
    "args": ["-y","@selfagency/beans-mcp"]
  }
}
```

## Documentation

## What beans-mcp MCP server does

The beans-mcp MCP server gives an MCP client programmatic access to a Beans issue-tracker workspace. It is intended for repositories or projects that already use the Beans CLI and store workspace data in the expected location. Agents can inspect existing work, create new beans, change their metadata and content, organize parent-child relationships, and manage completion states.

The server also exposes workspace-level file operations for `.beans` files and access to extension output logs or related guidance. This makes it useful when an agent needs more than issue records alone, such as reading or changing supported frontmatter or inspecting generated output.

## How it works

At launch, the process receives a workspace root either as a positional argument or through `--workspace-root`. It then uses the Beans CLI installed on the system, unless another executable is supplied with `--cli-path`. MCP requests are translated into operations against that workspace.

The beans-mcp MCP server checks the installed Beans CLI against supported version `0.4.2`. A mismatch writes a warning to standard error but does not stop startup. The server can listen on the default port `39173` or a port supplied at launch. Bulk create and bulk update requests run item by item and return separate success or error results rather than providing an all-or-nothing transaction.

## Setup and configuration

Run the package with a workspace path:

```bash
npx @selfagency/beans-mcp /path/to/workspace
```

Available command-line options include:

- `--workspace-root` or a positional path for the Beans workspace
- `--cli-path` to select the Beans executable
- `--port` to change the MCP server port; the default is `39173`
- `--log-dir` to set the log directory
- `-h` or `--help` to print usage information

No required environment variables are documented. The server expects the Beans CLI to be available at the configured path and a usable workspace to be supplied.

## Tools and capabilities

The beans-mcp MCP server provides tools for the following operations:

- Initialize a workspace with an optional prefix.
- View one bean or several beans by ID.
- Create or bulk-create beans, including parent assignments.
- Update metadata and body content, including status, type, priority, relationships, and optimistic concurrency hints.
- Bulk-update multiple beans.
- Query, filter, sort, search, or check ready items; the query tool also supports a GraphQL passthrough and an `llm_context` operation.
- Archive completed or scrapped beans, reopen them, or delete them.
- Mark Markdown checklist tasks inside a bean as complete.
- Read, edit, create, or delete files under `.beans`.
- Read extension output logs or display guidance.

## Limitations and notes

Path validation keeps file and log operations within the workspace or the VS Code log directory. Paths may be written with or without the `.beans/` prefix. Closing a parent cascades the selected closed status to descendants, while reopening a parent reopens closed descendants.

Cache behavior applies to unfiltered list results for short bursts, and mutation operations invalidate that cache. The `beans_bean_file` tool supports atomic frontmatter-only updates for documented fields such as `pr` and `branch`. Version incompatibility is reported as a warning rather than enforced, so behavior may depend on the installed Beans CLI version.

_Full upstream README: https://allmcps.com/mcp/beans-mcp/readme_