╔═╗┌─┐┌─┐┌─┐┌─┐┬┌┬┐┬┌─┐┌─┐
║  ├─┤├─┘├─┤│  │ │ │├┤ └─┐
╚═╝┴ ┴┴  ┴ ┴└─┘┴ ┴ ┴└─┘└─┘
         ╔╦╗╔═╗╔═╗
         ║║║║  ╠═╝
         ╩ ╩╚═╝╩

MCP Server for Capacities.io

</h1>

Search, create, and organize content in your Capacities knowledge base via AI

---

Important Limitations

The Capacities API does not support reading object content.

This MCP server can:

Search for objects by title (returns IDs and titles only)
Create new objects of any type
Write to daily notes and save weblinks

This MCP server cannot:

Read the actual content/body of any object
Retrieve notes, documents, or page contents
Export or analyze existing data

This is a limitation of the Capacities API, not this server. The API is in beta and Capacities may add read endpoints in the future.

---

What is this?

CapacitiesMCP is a Model Context Protocol server that connects AI assistants to Capacities.io for searching and creating content.

┌─────────────────────────────────────────────────────────────────┐
│                      Your AI Assistant                          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    CapacitiesMCP Server                         │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  REST API               │    X-Callback URLs            │   │
│  │  • Search by title      │    • Create objects           │   │
│  │  • List spaces          │    • Open in app              │   │
│  │  • Save weblinks        │    • Get current object info  │   │
│  │  • Add to daily note    │                               │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  [!] NO READ ACCESS TO OBJECT CONTENT (API limitation)          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                       Capacities.io                             │
└─────────────────────────────────────────────────────────────────┘

What You Can Actually Do

| Feature | Works? | Requires Desktop App | Details | |---------|--------|---------------------|---------| | List your spaces | Yes | No | Get space IDs and titles | | Search by title | Yes | No | Find objects, get IDs (not content) | | Get object types | Yes | No | See available structures in a space | | Create objects | Yes | Yes | Create Books, People, Meetings, custom types | | Save weblinks | Yes | No | Clip URLs with tags and notes | | Add to daily note | Yes | No | Append markdown to today's note | | Open objects | Yes | Yes | Deep-link into the desktop app | | Get current object | Yes | Yes | Get info about open object | | Read object content | NO | - | Not possible - API limitation | | Export data | NO | - | Not possible - API limitation | | Get page/note body | NO | - | Not possible - API limitation |

Installation

Prerequisites

Node.js 18+
Capacities.io Pro subscription (required for API access)
Capacities desktop app must be running (required for creating objects, opening objects, and getting current object info)

Quick Start

# Clone the repository
git clone https://github.com/ajokunu/capacities-mcp.git
cd capacities-mcp

# Install dependencies
npm install

# Build
npm run build

Configuration

1. Get Your API Key

Note: API access requires a Capacities Pro subscription.

Open Capacities desktop app
Go to Settings → Capacities API
Generate and copy your API key

2. Configure Your MCP Client

<details> <summary>Claude Code</summary>

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "capacities": {
      "command": "node",
      "args": ["/path/to/capacities-mcp/dist/index.js"],
      "env": {
        "CAPACITIES_API_KEY": "your_api_key_here"
      }
    }
  }
}

</details>

<details> <summary>Claude Desktop</summary>

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "capacities": {
      "command": "node",
      "args": ["/path/to/capacities-mcp/dist/index.js"],
      "env": {
        "CAPACITIES_API_KEY": "your_api_key_here"
      }
    }
  }
}

</details>

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | CAPACITIES_API_KEY | Yes | Your Capacities API key | | CAPACITIES_DEFAULT_SPACE_ID | No | Default space for operations | | CAPACITIES_CALLBACK_PORT | No | Port for x-callback responses (0 = auto) |

Available Tools

Search & Discovery

`capacities_list_spaces`

List all spaces you have access to.

`capacities_search`

Search for objects by title. Returns IDs and titles only, not content.

{
  "spaceId": "uuid-of-your-space",
  "searchTerm": "meeting notes"
}

`capacities_get_space_info`

Get info about a space including available structures.

`capacities_get_object_types`

List all object types (structures) available in a space.

Create & Write

`capacities_create_object`

Create any object type. Requires Capacities desktop app running.

{
  "type": "Book",
  "title": "Atomic Habits",
  "content": "Key insights from the book...",
  "tags": ["productivity", "habits"]
}

`capacities_save_weblink`

Save a URL with metadata.

{
  "spaceId": "uuid",
  "url": "https://example.com/article",
  "title": "Great Article",
  "tags": ["research"]
}

`capacities_add_to_daily_note`

Append content to today's daily note.

{
  "spaceId": "uuid",
  "content": "## Meeting Summary\n- Discussed roadmap"
}

Utility

`capacities_get_current_object`

Get info (URL, title) about the currently open object. Does not return content.

`capacities_open_object`

Open a specific object by its URL in the desktop app.

Usage Examples

Things you can ask your AI assistant:

"List all my Capacities spaces"

"Search for 'project planning' in my work space"

"Create a new Book called 'Deep Work' with notes about focus"

"Save this URL to my research space"

"Add a summary to today's daily note"

Things you cannot do:

~~"Read my meeting notes from last week"~~

~~"Summarize my research documents"~~

~~"Export all my notes about X topic"~~

Rate Limits

| Endpoint | Limit | |----------|-------| | /spaces, /space-info | 5 req/60s | | /lookup | 120 req/60s | | /save-weblink | 10 req/60s | | /save-to-daily-note | 5 req/60s |

Why No Read Access?

The Capacities API is in early beta. From their docs:

"The Capacities API is in a very early stage. Many endpoints you'd expect for a REST API are not yet available."

There is no /get-object or similar endpoint. The x-callback URL scheme also only returns metadata (URL, title), not content.

If you want this feature, request it from Capacities directly.

Development

npm run dev        # Watch mode
npm run typecheck  # Type checking
npm run build      # Build

License

MIT

---

Built for the Capacities and MCP communities Waiting patiently for Capacities to add read endpoints...

CapacitiesMCP