Capacities MCP Server

An MCP server for Capacities: search, property-based object lookup, object CRUD, save weblinks, and daily notes from any MCP-compatible client.

⚠️ Use 2.x. Version 2.x runs on Capacities' current REST API. Version 1.x used the Capacities Beta API, which Capacities scheduled for discontinuation on September 1, 2026; 1.x builds (and any .dxt packaged before v2.0.0) depend on it. Reinstall the current capacities-desktop-extension.dxt (v2.x). See the Capacities API notice.

About the name "v2". Capacities' own docs call the current API "v1" (their Beta was the first API). This repo calls it v2 because it is the second API this server has run on. Same API, two names.

Prerequisites

• A Capacities account with API access

• An API token: Capacities desktop app → Settings → Capacities API → Generate new token. Each token is scoped to one space and is either read-only or read-write; tools that write need a read-write token.

• To run from source: Node.js 22 (the version the Docker image runs)

Related MCP server: Capacities-MCP-Plus

Installation

Choose the option that fits your setup:

Option 1: Claude Desktop Extension (Easiest)

1. Download capacities-desktop-extension.dxt

2. In Claude Desktop: Settings → Extensions → Import Extension

3. Select the .dxt file and enter your API token when prompted

All dependencies are bundled; no additional setup needed.

Option 2: Run from Source

git clone https://github.com/inconceivablelabs/capacitiesMCP.git
cd capacitiesMCP
npm install
npm run build

Then add to your MCP client config (e.g. Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "capacities": {
      "command": "node",
      "args": ["/path/to/capacitiesMCP/server/dist/index.js"],
      "env": {
        "CAPACITIES_API_TOKEN": "your_token_here"
      }
    }
  }
}

Option 3: Docker Container

For running as a persistent service (e.g. behind an MCP gateway):

# Build from the repo root: the Dockerfile copies from both src/ and server/.
docker build -f server/Dockerfile -t capacities-mcp .
docker run -d \
  -e CAPACITIES_API_TOKEN=your_token_here \
  capacities-mcp

The image is based on node:22-slim. Its runtime stage installs only server/'s production dependencies and the compiled output, with no source or dev dependencies. Since 2.2.3 it also removes the base image's bundled npm/npx, which the server never runs.

Available tools

Single-space per token. A v2 API token is scoped to exactly one space; list_spaces returns that one space. To work with multiple spaces, use multiple tokens.

The object model: properties vs. body

Objects in Capacities hold two kinds of content, and the tools treat them differently:

• Properties — the object's typed fields: title, text, dates, numbers, labels (e.g. a task's Status, a weblink's Category), and entity relations (tags, a meeting's attendees). Set these with the properties / labels / relations inputs on create_object / update_object, keyed by property name or id (get them, plus label options and relation targets, from get_space_info). Relations and labels are set by name and resolved strictly: an unknown name is an error, never a guess; pass create_missing_relations: true to auto-create unmatched relation targets.

• Body — freeform Markdown, set via the body / notes / content / markdown parameter.

Rule of thumb: set structured things as properties, prose as body. A tag is a property (a relations entry), not a [[link]] typed into the text. One tool call completes one object (all its properties and its body); several distinct, standalone objects take several calls.

Markdown conventions (body)

Any body/notes field supports Capacities' inline conventions:

Use [[Name]] to reference something that already exists; use () / # when you intend to create the task/tag.

Weblinks & media objects (current API limitation)

save_weblink creates a Weblink from a URL and auto-fetches the page's title and description; you can override title and description at save time. Those are the only properties settable on a weblink. The Capacities API currently treats media objects (weblinks, PDFs, images, audio, files) as create-only: they cannot be updated after creation, so tags, Category, and Topic cannot be set on a weblink through the API. To tag a weblink today, put a #tag in its notes (this associates a Tag via the body).

This is an upstream Capacities API limitation, not a limitation of this server. As soon as the Capacities API allows updating media objects, this server will add full weblink property support (tags / Category / Topic via save_weblink). Until then, #tag-in-notes is the available path.

Rate limits

Capacities enforces rate limits on its servers, per token and per endpoint (see its rate-limiting docs). In our measurements against /object the window is rolling: slots free up one at a time as each request ages out of the trailing 60 seconds. This server also runs a client-side, per-endpoint limiter, and its multi-call tools (create_object/update_object with many relations, and find_objects' searches and object reads) pace themselves against it. A find_objects listing does not wait: when the window is full it stops as a partial, with a Note: line saying so. That limiter is best-effort: it cannot see other clients using the same token or network. If a tool returns RATE_LIMIT_EXCEEDED, wait and retry rather than trying to predict the window.

The API sits behind Cloudflare, so a server-side rejection can arrive as a Cloudflare "you are being rate limited" page. The one we have captured came on a 429; the server also treats the same page on a 403 as a rate limit, in case a ban arrives that way. Both are reported as RATE_LIMIT_EXCEEDED. Such a ban is per IP address, so it affects every client on the same network for as long as it lasts. Error messages carry the server's response trimmed to fit: a JSON error is kept whole so the model can correct its call, and an HTML page is cut to its first line.

Why this server?

As of 2026-10-21: @capacities/api 1.1.3, and the official MCP server as documented at docs.capacities.io/developer/model-context-protocol. Both are moving, so check them before relying on this table.

Pick the official server if you want block-level editing, file uploads, OAuth instead of a token, or a connector that works in hosted chat apps with nothing to install. Pick the SDK if you are writing your own code: it is the complete client. Note that 1.1.3 needs zod 4 at runtime even though its peer range also allows zod 3 (under zod 3.25 its import fails with .meta is not a function). Pick this server if your MCP client does typed, relation-heavy writes that must be validated before anything is saved, or needs to find objects by property value.

Configuration

Project structure

capacitiesMCP/
├── src/                  # TypeScript source (single source of truth)
├── server/               # Runtime packaging
│   ├── Dockerfile        # Container build
│   ├── package.json      # Runtime dependencies only
│   └── dist/             # Compiled output (built from root src/)
├── tsconfig.json         # Builds src/ → server/dist/
├── manifest.json         # DXT extension manifest
└── *.dxt                 # Pre-built extension packages

npm run build compiles src/ directly into server/dist/. There is one source, one build step, and one output location used by all three installation methods.

Development

npm install
npm run build        # Compile TypeScript
npm run dev          # Watch mode
npm run inspector    # MCP Inspector for debugging
npm test             # Run tests

See CLAUDE.md for architecture details.

Security advisories and reachability

This server speaks MCP over stdio only. It imports two modules from @modelcontextprotocol/sdk (server/mcp.js and server/stdio.js); the SDK's HTTP transports, OAuth client/server code and Express/Hono middleware are installed as dependencies but never loaded. Most advisories that Dependabot raises against this repo therefore cannot be reached at runtime. We still patch them, because the lockfiles ship in the Docker image and the extension.

As of 2.1.2 (SDK 1.32.1), npm audit reports 0 in both lockfiles. Reachability of the advisories cleared in that release, checked against a module-resolution trace of a live stdio session (initialize, tools/list, tools/call, resources/list):

Image scanners also used to flag ip-address 10.1.0 inside the npm CLI bundled with the node:22-slim base image. That copy is in no lockfile, so Dependabot cannot see it, and the server never runs npm. Since 2.2.3 the runtime image no longer contains npm at all.

License

MIT. See LICENSE.