@randomfact/can-mcp
v0.1.2
Published
MCP server for Can: Just the right amount of Kanban, by Random Fact
Readme
@randomfact/can-mcp
Local MCP server that wraps the Can public API as MCP tools, so an LLM agent (Claude Desktop, MCP Inspector, etc.) can read and write your KanbanCan workspaces on your behalf.
What it does
- Translates each Can REST operation into an MCP tool, derived from the published OpenAPI spec at
https://api.can.randomfact.com/v1/openapi.json. New API routes appear as new tools automatically — no package update needed. - Authenticates to Can via OAuth 2.0 + PKCE on demand. The first tool call pops a browser tab for sign-in; subsequent calls reuse a cached token. There is no separate
loginsubcommand — adding the package to your MCP client config and restarting is the entire setup. - Runs as a local process. Tokens are stored in a per-user file under the OS config directory with
0600permissions on POSIX. No keychain dependency.
Install / config
Claude Code (CLI)
Register the server with claude mcp add. Scope it to your user so it's available in every project:
claude mcp add can --scope user -- npx -y @randomfact/can-mcp(Drop --scope user to limit it to the current project, or use --scope project to write a .mcp.json that you can check into your repo.)
Verify with:
claude mcp listIn a new Claude Code session, run /mcp to confirm can is connected, then ask the agent something like "list my Can workspaces". A browser tab pops on the first tool call, you sign in once, the chat continues with the workspace list.
Claude Desktop
Add this entry to your Claude Desktop config (claude_desktop_config.json — %APPDATA%\Claude\ on Windows, ~/Library/Application Support/Claude/ on macOS, ~/.config/Claude/ on Linux):
{
"mcpServers": {
"can": {
"command": "npx",
"args": ["-y", "@randomfact/can-mcp"]
}
}
}Quit and reopen Claude Desktop (it loads MCP config at startup; in-app reload won't pick up edits). Ask the chat "list my Can workspaces". Same flow: browser pops once, sign-in, chat continues. The next tool call reuses the cached token; no second browser pop unless the refresh token has been revoked or has expired.
Other MCP clients
Anything that follows the MCP stdio transport protocol works the same way — point it at npx -y @randomfact/can-mcp with no other configuration. For SSE / HTTP transport, run the server explicitly with --transport=http --port 3100 and point your client at http://localhost:3100/sse.
Token storage
Tokens are persisted to a per-user file under the OS config directory:
| Platform | Path |
|----------|------|
| Linux | $XDG_CONFIG_HOME/can-mcp/tokens.json (defaults to ~/.config/can-mcp/tokens.json) |
| macOS | ~/Library/Application Support/can-mcp/tokens.json |
| Windows | %APPDATA%\can-mcp\tokens.json |
POSIX writes use chmod 0600. To force re-authentication, delete the file.
Flags
npx @randomfact/can-mcp accepts only flags — no positional arguments, no subcommands. All arguments are optional.
| Flag | Default | Notes |
|------|---------|-------|
| --base-url <url> | https://api.can.randomfact.com | API + OAuth base URL. The Can API and OAuth server share one hostname mapped directly to the underlying Cloud Run service. (The SPA at can.randomfact.com is a separate Firebase Hosting site that the MCP package never talks to.) |
| --openapi-path <path> | (live ${baseUrl}/v1/openapi.json) | Read the OpenAPI spec from a local file instead of the live URL. |
| --client-id <id> | can-mcp | OAuth client ID. Override when running against a non-production deployment. |
| --token-store <path> | OS-default path | Override the token cache location. |
| --scope <scope> | (none) | OAuth scope. v1 uses an empty scope. |
| --manual-code | off | Use the urn:ietf:wg:oauth:2.0:oob redirect URI: prints the authorize URL to stderr and reads the code from stdin. For SSH / headless containers without a browser. |
| --loopback-port <port> | random | Pin the loopback callback port. Useful when your registered redirect URIs require a specific port. |
| --transport stdio\|http | stdio | Use http to expose the MCP server over SSE on --port. Stdio is the right choice for Claude Desktop and most local MCP clients. |
| --port <n> | 3100 | HTTP transport port. Ignored in stdio mode. |
Environment variables: CAN_BASE_URL, CAN_OPENAPI_PATH, CAN_MCP_CLIENT_ID, CAN_MCP_TOKEN_STORE, CAN_MCP_LOG_LEVEL (debug / info / warn / error).
Tools (current)
The tool list is derived from the OpenAPI spec at startup, so this list grows as the API grows. v1 ships with at least:
list_workspaces— list the caller's workspace membershipsget_workspace— get one workspace by sluglist_boards/get_boardlist_columnslist_tickets/get_ticketcreate_ticket/update_ticket— both accept an optionalagentAssigneeIdslug-format string (^[a-z][a-z0-9-]*$, max 40 chars). Use it to claim a ticket on behalf of an AI coding agent. Curated ids that render with a brand glyph in the SPA:claude(Claude),openai(ChatGPT),copilot(GitHub Copilot),cursor(Cursor),gemini(Gemini). Any other slug-valid id is also accepted and renders in the SPA with an initials avatar — the API does not gate writes on the curated list. PassagentAssigneeId: nullto clear the assignment. The MCP server does NOT auto-claim assignment based on the calling client's identity; pass the field explicitly when you mean to.bulk_status_tickets— move many tickets between columnssearch_tickets— workspace-scoped semantic search ranked by cosine distance to the query (smaller is closer). Each ticket is embedded server-side from itstitle,description, and non-deleted comments; the embedding refreshes whenever any of those change. Accepts optionalboardKey(repeatable) to scope to one or more boards,limit(default 25, max 100), andmaxDistance(default 0.6) to drop low-confidence matches. Example: "find the ticket about the OAuth callback redirect" — the agent callssearch_ticketsand surfaces the closest match by title even when the query shares no literal words with the ticket.
Activity entries written via this MCP server include via: "api:Can MCP" so workspace audit trails can distinguish integration writes from direct user clicks.
Agent skills
The server also ships short workflow guidance to LLM-driven clients via MCP's instructions field (loaded once into the session's system prompt) and a complementary get_help tool for longer reference content. There is no extra setup — an MCP client that respects instructions (Claude Code, Claude Desktop, Cursor) receives the guidance on first connection.
- The always-loaded content lives in skills/instructions.md. It names the agent ticket workflow — read, self-assign via
agentAssigneeId, move to an in-progress column, do the work, move to done, confirm — and points toget_helpfor detail. get_help(no arguments) returns an index of available topics.get_helpwithtopic: "agent-ticket-workflow"returns the long-form walkthrough with worked examples (skills/agent-ticket-workflow.md).- Adding new topics is package-side only: drop
skills/<slug>.md(level-1 heading + summary paragraph) into the npm package, rebuild, publish. No API or OpenAPI spec change required.
License
MIT.
