Beans Mcp
Beans is a local-first issue tracker that lives in `.beans` folders, and this MCP server gives Claude full programmatic access to it. You get tools for creating, updating, querying, and archiving beans, plus bulk operations for batch work. The `beans_query` tool handles listing, filtering, and sorting with GraphQL passthrough. The `beans_update` tool consolidates status, priority, parent reassignment, body edits, and blocking relationships into one call with optimistic concurrency support. File operations let you read and write bean markdown files and frontmatter fields like branch and PR links. It validates paths to keep everything scoped to your workspace, caches unfiltered list results with automatic invalidation on mutations, and warns but doesn't block on CLI version mismatches.
- tools
- 13
- transport
- STDIO
- last updated
- Feb 27, 2026
Tools
13 toolsPublic tool metadata for what this MCP can expose to an agent.
beans_initInitialize the workspace (optional `prefix`).
Initialize the workspace (optional `prefix`).
No parameter schema in public metadata yet.
beans_archiveArchive completed/scrapped beans.
Archive completed/scrapped beans.
No parameter schema in public metadata yet.
beans_viewFetch full bean details by `beanId` or `beanIds`.
Fetch full bean details by `beanId` or `beanIds`.
No parameter schema in public metadata yet.
beans_createCreate a new bean (title/type + optional body/parent).
Create a new bean (title/type + optional body/parent).
No parameter schema in public metadata yet.
beans_bulk_createCreate multiple beans in one call, optionally under a shared parent.
Create multiple beans in one call, optionally under a shared parent.
No parameter schema in public metadata yet.
beans_updateConsolidated metadata + body updates (status/type/priority/parent/clearParent/blocking/blockedBy/body/bodyAppend/bodyReplace) plus optional optimistic concurrency hint (`ifMatch`).
Consolidated metadata + body updates (status/type/priority/parent/clearParent/blocking/blockedBy/body/bodyAppend/bodyReplace) plus optional optimistic concurrency hint (`ifMatch`).
No parameter schema in public metadata yet.
beans_bulk_updateUpdate multiple beans in one call, optionally reassigning them to a shared parent.
Update multiple beans in one call, optionally reassigning them to a shared parent.
No parameter schema in public metadata yet.
beans_complete_tasksMark all markdown checklist tasks within a bean as complete.
Mark all markdown checklist tasks within a bean as complete.
No parameter schema in public metadata yet.
beans_deleteDelete one or many beans (`beanId` or `beanIds`, optional `force`).
Delete one or many beans (`beanId` or `beanIds`, optional `force`).
No parameter schema in public metadata yet.
beans_reopenReopen a completed or scrapped bean to an active status.
Reopen a completed or scrapped bean to an active status.
No parameter schema in public metadata yet.
beans_queryUnified list/search/filter/sort/ready operations, with GraphQL passthrough.
Unified list/search/filter/sort/ready operations, with GraphQL passthrough.
No parameter schema in public metadata yet.
beans_bean_fileRead/edit/create/delete files under `.beans`.
Read/edit/create/delete files under `.beans`.
No parameter schema in public metadata yet.
beans_outputRead extension output logs or show guidance.
Read extension output logs or show guidance.
No parameter schema in public metadata yet.
Sponsors
Agent CaffeineSponsoredClose your lid, come back to finished work
SnugSponsoredThe clipboard manager for the AI eraPromote your product hereReach 125k+ visitors monthly
WaxSponsoredBlock anything with supervision, without erasing your iPhonePromote your product hereReach 125k+ visitors monthly
knobsSponsoredSee your site on any phone, any day, in any languageReadme
@voxslopuli/beans-mcp 🫘
beans-mcp icon
MCP (Model Context Protocol) server for Beans issue tracker. Provides programmatic and CLI interfaces for AI-powered interactions with Beans workspaces.
Documentation: beans-mcp.voxslopuli.org
🤖 Try Beans fully-integrated with GitHub Copilot in VS Code! Install the selfagency.beans-vscode extension.
Usage
npx @voxslopuli/beans-mcp /path/to/workspace
Bundled beans CLI
Details
- Repository
- github.com/selfagency/beans-mcp
- Package
@selfagency/beans-mcp- Transport
- STDIO
- Registry
- MCP registry, active