Skip to content

MCP (Model Context Protocol)

homecloud-mcp is the platform MCP server for AI assistants (Cursor, Claude Desktop, etc.). It speaks MCP over stdio and calls HomeCloud through the Python SDK — not the CLI binary.

Design

  • One server for the whole platform; tool names are prefixed by service (tasks_search, future mq_*, so_*, …).
  • Core handles auth (HomeCloudClient), tool registry, error shaping, and read-only/destructive hints.
  • Modules implement each service. Tasks shipped first; add modules by registering them in the package (see the project README).

Auth

Same as Tasks CLI / SDK:

  • homecloud login (console JWT), or
  • User-bound Access Key in ~/.homecloud/credentials / env (HC_PROFILE, HOMECLOUD_ACCESS_KEY_ID, …).

Service-account keys cannot act as a Tasks user.

Install and run

pip install homecloud-mcp homecloud-sdk
homecloud-mcp

Cursor

{
  "mcpServers": {
    "homecloud": {
      "command": "homecloud-mcp",
      "env": { "HC_PROFILE": "default" }
    }
  }
}

See the homecloud-mcp README for a full tool list and module extension guide.

Tasks tools (first module)

Search, get (read-only by default), schema, people, create/update/transition, bulk upsert/delete, comments (edit/delete), activity (discussion + history), comment_file_url (chat attachments via so_uri), labels, relations/links, archive/restore, watch, shares, projects (list/create), and delete (confirm=true). Use tasks_schema before tasks_transition.