CapacitiesMCP

<p align="center"> <img src="https://img.shields.io/badge/MCP-Server-blue?style=for-the-badge" alt="MCP Server"> <img src="https://img.shields.io/badge/Capacities.io-Integration-purple?style=for-the-badge" alt="Capacities Integration"> <img src="https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript"> </p>

<h1 align="center">

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

MCP Server for Capacities.io

</h1>

<p align="center"> <b>Search, create, and organize content in your Capacities knowledge base via AI</b> </p>

---

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.

1. Open Capacities desktop app
2. Go to Settings → Capacities API
3. Generate and copy your API key

2. Configure Your MCP Client

<details> <summary><b>Claude Code</b></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><b>Claude Desktop</b></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

---

<p align="center"> _{Built for the Capacities and MCP communities}<br> _{Waiting patiently for Capacities to add read endpoints...} </p>