capacities

This Capacities MCP server exposes a set of MCP endpoints that map directly to the Capacities API. It allows you to list your Spaces, fetch detailed information about a Space, perform cross-space content searches, save web links with metadata to Spaces, and append content to your daily notes. The included tools correspond to Capacities functionality: capacities_list_spaces enumerates all of your personal spaces; capacities_get_space_info returns space structures and collections; capacities_search lets you query across spaces with optional filtering; capacities_save_weblink saves a URL with optional metadata to a chosen space; and capacities_save_to_daily_note appends Markdown content to today’s daily note in a specified space. You’ll typically configure an API key for authentication and then invoke these tools through your MCP client on Claude or via your own environment that consumes MCP prompts. Ensure your Capacities API key is kept secure and provided to the MCP server via the environment variable CAPACITIES_API_KEY.

Prerequisites:

• Node.js and npm (for npx usage) or Bun if you prefer the development workflow described below.
• A Capacities API key (from your Capacities account settings).
• Access to the internet to download the MCP package when using npx.

Option A: Claude Desktop setup (no local build required)

1. Ensure Claude Desktop is installed.
2. Add the MCP server configuration to your Claude Desktop config file, typically at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS:

{
  "mcpServers": {
    "capacities": {
      "command": "npx",
      "args": ["-y", "capacities-mcp"],
      "env": {
        "CAPACITIES_API_KEY": "your_capacities_api_key_here"
      }
    }
  }
}

3. Replace the API key with your actual Capacities API key. The server will be downloaded and run automatically when Claude Desktop starts.

Option B: Local development (clone and build)

1. Clone the repository and enter the project:

git clone https://github.com/jemgold/capacities-mcp.git
cd capacities-mcp

2. Install dependencies (using Bun is recommended for this project):

bun install

3. Create an environment file from the example and configure your API key:

cp .env.example .env

CAPACITIES_API_KEY=your_api_key_here

4. Build the server:

bun run build

5. Run for development:

bun run dev

6. For production, you can start the prebuilt server:

bun run start

Optional utilities for development:

• Inspect the available tools and schema:

bun run inspect

• Run tests:

bun run test

• Lint and format code:

bun run lint

Tips and notes:

• Always provide CAPACITIES_API_KEY in the environment variable to authenticate requests to Capacities.
• The MCP exposes a curated set of tools that mirror Capacities capabilities; use capacities_list_spaces to discover your spaces before targeting specific ones with other tools.
• Be mindful of Capacities API rate limits described in the documentation to avoid throttling.
• If you switch from development to production, ensure your build is up to date and that you provide a secure API key through the environment.
• When using Claude Desktop, the npx approach will fetch capacities-mcp automatically; ensure your network allows this download.
• If you encounter authentication errors, regenerate or revalidate your Capacities API key in your Capacities account; confirm the key is active and correctly set in the environment.
• The npm package name for this server is capacities-mcp, which can be used in alternative deployment pipelines if you’re not using Claude Desktop.