Log inSubmit server
Beans MCP logo

Beans MCP

Manage Beans issue-tracker workspaces through MCP tools for querying, creating, updating, and organizing beans.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Beans MCP

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "beans-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@selfagency/beans-mcp"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

We couldn’t confirm it starts correctly

We ran the install command but it didn't respond within our test window — this can mean a slow first-time install rather than a real problem.

npx -y @selfagency/beans-mcp

No response to initialize.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked 5d ago.

Overview

The beans-mcp MCP server connects AI agents to the Beans CLI issue tracker and its workspace files. It exposes MCP tools for searching, viewing, creating, updating, deleting, archiving, and reopening beans, plus editing files under `.beans`. The server starts against a selected workspace and invokes the installed Beans CLI, with options for the CLI path, port, and logs. Reach for it when an agent needs to manage Beans issues or generate workspace-aware context.

Use cases

  • Query ready Beans issues for an agent
  • Create tasks under an existing parent bean
  • Update statuses and priorities in bulk
  • Inspect or edit `.beans` workspace files
  • Archive or reopen completed work

Key features

  • Search, filter, sort, and query Beans workspaces
  • Create and update individual or bulk beans
  • Manage parent-child relationships and statuses
  • Read and modify `.beans` files
  • Archive, delete, and reopen beans
  • Inspect extension output logs

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 3d ago

Recent health check succeeded.

8/8 checks healthy over the last 50d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 15d ago via OSV.dev · @selfagency/beans-mcp (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

npm downloads209Package downloads in the last 30 days.
Last commit5mo agoMost recent push to the default branch.
Install checkInconclusiveDidn't respond in our test window — often a slow first install.
Directory activity1 viewsConfig copies, upvotes, and views on AllMCPs.

How Beans MCP works

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:

Terminal
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.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Beans MCP

beans-mcp is an MCP server that connects AI clients to the Beans CLI issue tracker and workspace. Its main tools query and view beans, create and update issues individually or in bulk, manage statuses and relationships, edit `.beans` files, archive or reopen work, and read extension output logs.

Run it with npx and provide a Beans workspace path: `npx @selfagency/beans-mcp /path/to/workspace`. You can also pass `--workspace-root`, `--cli-path`, `--port`, or `--log-dir` to configure startup.

It documents MCP usage and specifically mentions integration with GitHub Copilot in VS Code through the separate `selfagency.beans-vscode` extension.

The server compares the installed Beans CLI with version `0.4.2`. If the versions differ, it prints a warning to standard error and continues starting instead of blocking use.

Yes. Use `beans_bulk_update` to update multiple beans and `beans_bulk_create` to create several beans. These operations process items sequentially and return per-item success or error results rather than acting atomically.

Related MCP servers

All in Product Management All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewBeans MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/beans-mcp?style=directory)](https://allmcps.com/mcp/beans-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/beans-mcp"><img src="https://allmcps.com/api/badge/beans-mcp?style=directory" alt="Beans MCP on AllMCPs" /></a>