Beans MCP
@The Self Agency LLC
@selfagency/beans-mcp 🫘
👁 beans-mcp icon
👁 Test & Build
👁 codecov
👁 NPM Version
MCP (Model Context Protocol) server for Beans issue tracker. Provides programmatic and CLI interfaces for AI-powered interactions with Beans workspaces.
Documentation: beans-mcp.self.agency
🤖 Try Beans fully-integrated with GitHub Copilot in VS Code! Install the selfagency.beans-vscode extension.
Usage
npx @selfagency/beans-mcp /path/to/workspace
Versioning
@selfagency/beans-mcp has its own package versioning. Compatibility with the
Beans CLI is tracked separately.
At startup, the server compares the installed beans CLI version against the
hardcoded supported Beans version: 0.4.2. If they differ, it prints a warning
to stderr and continues startup.
Parameters
--workspace-rootor positional arg: Workspace root path--cli-path: Path to Beans CLI--port: MCP server port (default: 39173)--log-dir: Log directory-h,--help: Print usage and exit
Summary of public MCP tools
| Tool | Description |
|---|---|
beans_init | Initialize the workspace (optional prefix). |
beans_archive | Archive completed/scrapped beans. |
beans_view | Fetch full bean details by beanId or beanIds. |
beans_create | Create a new bean (title/type + optional body/parent). |
beans_bulk_create | Create multiple beans in one call, optionally under a shared parent. |
beans_update | Consolidated metadata + body updates (status/type/priority/parent/clearParent/blocking/blockedBy/body/bodyAppend/bodyReplace) plus optional optimistic concurrency hint (ifMatch). |
beans_bulk_update | Update multiple beans in one call, optionally reassigning them to a shared parent. |
beans_complete_tasks | Mark all markdown checklist tasks within a bean as complete. |
beans_delete | Delete one or many beans (beanId or beanIds, optional force). |
beans_reopen | Reopen a completed or scrapped bean to an active status. |
beans_query | Unified list/search/filter/sort/ready operations, with GraphQL passthrough. |
beans_bean_file | Read/edit/create/delete files under .beans. |
beans_output | Read extension output logs or show guidance. |
Examples
Programmatic usage
Installation
npm install beans-mcp
Example
import { createBeansMcpServer, parseCliArgs } from '@selfagency/beans-mcp';
const server = await createBeansMcpServer({
workspaceRoot: '/path/to/workspace',
cliPath: 'beans', // or path to beans CLI
});
// Connect to stdio transport or your own transport
API
createBeansMcpServer(opts)
Creates and initializes a Beans MCP server instance.
Options:
workspaceRoot(string): Path to the Beans workspacecliPath(string, optional): Path to Beans CLI executable (default: 'beans')name(string, optional): Server name (default: 'beans-mcp-server')version(string, optional): Server versionlogDir(string, optional): Directory for server logsbackend(BackendInterface, optional): Custom backend implementation
Returns: { server: McpServer; backend: BackendInterface }
startBeansMcpServer(argv)
CLI-compatible entrypoint for launching the server.
Utility Functions
parseCliArgs(argv: string[]): Parse CLI argumentsisPathWithinRoot(root: string, target: string): boolean: Check if path is contained within rootsortBeans(beans, mode): Sort beans by specified mode
Types & Schemas
Export of GraphQL schema, Zod validation schemas, and TypeScript types for Beans records and operations.
Agent Skills (skills-npm, skills.sh)
This package ships a built-in Agent Skill under skills/ and also publishes that skill in a format that fits the broader open skills ecosystem surfaced by skills.sh.
- Skill path in package:
skills/beans-mcp/SKILL.md - Published skill artifact:
https://beans-mcp.self.agency/.well-known/agent-skills/beans-mcp/SKILL.md - Published discovery index:
https://beans-mcp.self.agency/.well-known/agent-skills/index.json - Compatible with discovery tools that scan:
node_modules/**/skills/*/SKILL.md
That means you can use it with npm-based workflows such as skills-npm, while also pointing ecosystem tooling at the published skill artifact and discovery index used by skills catalogs like skills.sh.
To symlink installed npm-packaged skills into your agent workspace, you can use skills-npm in your consuming project.
License
MIT
Server Config
{
"mcpServers": {
"beans": {
"command": "npx",
"args": [
"-y",
"@selfagency/beans-mcp@latest",
"/path/to/your/repo"
]
}
}
}