kibela

Kibela MCP Server exposes a local MCP-compatible interface that can be used by MCP clients (such as Claude Desktop or VSCode) to interact with Kibela data. It implements a subset of GraphQL-based tools that allow you to search notes, fetch and modify note content, manage folders, and handle comments and related operations within Kibela. The server is designed to run locally via Docker in the documented setup, and it expects environment variables for authentication and origin so clients can securely connect to Kibela.

To use the server, configure your MCP client to point at the Kibela MCP Server and provide the necessary Kibela origin and access token. Common workflows include searching for notes to summarize, organizing notes into folders, creating or updating notes, and attaching notes to folders. The available tools cover note operations (search, retrieve by relay ID, get by path or URL, create, update), folder operations (search, fetch by relay ID, get folders, create, move notes, attach notes), and comment operations (create comments and replies). There are also utility endpoints for getting Kibela groups and feed sections. You can customize tool descriptions and prompts by supplying a JSON modification file and mounting it into the container or including it in your local configuration.

If you’re using a tool like Claude Desktop, you’ll typically provide a mcpServers configuration referencing the docker image as shown in the installation section, and then run your MCP client with that configuration loaded. The server communicates with Kibela via origin and token, so ensure those environment variables are set correctly in your client configuration.

Prerequisites:

• Docker must be installed and running
• Kibela access tokens must be issued
• An MCP client capable of connecting to a local MCP server (e.g., Claude Desktop or VSCode MCP client)

Option 1: Run with Docker (recommended)

1. Ensure Docker is running on your machine.
2. Run the Kibela MCP Server container with the required environment variables:

# Example: start the Kibela MCP Server via Docker
docker run -it \
  -e KIBELA_ORIGIN=https://your-subdomain.kibe.la \
  -e KIBELA_ACCESS_TOKEN=your_token_here \
  -v /path/to/kibela-mcp-server-config.json:/usr/src/app/kibela-mcp-server-config.json \
  ghcr.io/kibela/kibela-mcp-server

3. If desired, mount a custom MCP configuration file to /usr/src/app/kibela-mcp-server-config.json and reference it in your client configuration.

Option 2: No Docker (local script)

1. If you prefer not to use Docker, use the local script path as shown below (absolute path required).
2. Prepare the same environment variables and run the script with your MCP client.

{
  "mcpServers": {
    "kibela": {
      "command": "/path/to/kibela-mcp-server/bin/cli.mjs",
      "env": {
        "KIBELA_ORIGIN": "https://your-subdomain.kibe.la",
        "KIBELA_ACCESS_TOKEN": "***"
      }
    }
  }
}

Note: When using the Docker approach, make sure Docker is configured to access the GHCR image and that your Kibela origin and token are valid.

Tips and considerations:

• Always provide KIBELA_ORIGIN and KIBELA_ACCESS_TOKEN to enable the MCP server to authenticate with Kibela.
• The server currently exposes functionality via public Kibela GraphQL APIs suitable for MCP tooling; not all Kibela features may be available through MCP.
• If you customize tools or prompts, you can mount a config JSON (e.g., kibela-mcp-server-config.json) into the container to override tool descriptions and prompts.
• For Docker users: ensure the image ghcr.io/kibela/kibela-mcp-server is accessible (you may need to login to GHCR depending on your environment).
• If you encounter permission or path issues, use absolute paths for any local script execution and ensure the container has access to any mounted config files.
• Check the MCP client’s documentation to understand how to pass the mcpServers configuration and how to reference environment variables in your client UI.