Kibela MCP server for AI agents

The Kibela MCP Server provides seamless integration with the Kibela API, allowing language models to interact with and manipulate Kibela content. This server implements the Model Context Protocol (MCP) to enable AI tools to search, retrieve, and manage your Kibela notes and resources.

Installation Options

NPM Installation

You can quickly install and run the Kibela MCP Server using NPM:

npx -y @kiwamizamurai/mcp-kibela-server

Docker Installation

Alternatively, you can use the Docker image:

docker run -i --rm -e KIBELA_TEAM=YOUR_TEAM_NAME -e KIBELA_TOKEN=YOUR_TOKEN ghcr.io/kiwamizamurai/mcp-kibela-server:latest

Configuration

Required Environment Variables

Before using the server, you must set these required environment variables:

KIBELA_TEAM: Your Kibela team name
KIBELA_TOKEN: Your Kibela API token

Cursor Integration

Add the following to your ~/.cursor/mcp.json file to integrate with Cursor:

{
    "mcpServers": {
        "kibela": {
            "command": "npx",
            "args": ["-y", "@kiwamizamurai/mcp-kibela-server"],
            "env": {
                "KIBELA_TEAM": "YOUR_TEAM_NAME",
                "KIBELA_TOKEN": "YOUR_TOKEN"
            }
        }
    }
}

For Docker-based integration:

{
    "mcpServers": {
        "kibela": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "KIBELA_TEAM",
                "-e",
                "KIBELA_TOKEN",
                "ghcr.io/kiwamizamurai/mcp-kibela-server:latest"
            ],
            "env": {
                "KIBELA_TEAM": "YOUR_TEAM_NAME",
                "KIBELA_TOKEN": "YOUR_TOKEN"
            }
        }
    }
}

Available Tools

Note Searching and Retrieval

Search Notes

kibela_search_notes

Search Kibela notes with advanced filtering options:

query (string): Search query
coediting (boolean, optional): Filter by co-editing status
isArchived (boolean, optional): Filter by archive status
sortBy (string, optional): Sort by (RELEVANT, CONTENT_UPDATED_AT)
userIds (string[], optional): Filter by user IDs
folderIds (string[], optional): Filter by folder IDs

Get Your Notes

kibela_get_my_notes

Retrieve your latest notes:

limit (number, optional): Number of notes to fetch (default: 15)

Get Note Content

kibela_get_note_content

Retrieve complete content of a specific note:

id (string): Note ID
include_image_data (boolean, optional): Whether to include image data URLs (default: false)

Get Note by Path

kibela_get_note_from_path

Get note content using its path or URL:

path (string): Note path (e.g. '/group/folder/note') or full Kibela URL
include_image_data (boolean, optional): Whether to include image data URLs (default: false)

Group and Folder Management

List Groups

kibela_get_groups

Get all accessible groups with details about privacy settings and permissions.

List Group Folders

kibela_get_group_folders

List folders within a group:

groupId (string): Group ID
parentFolderId (string, optional): Parent folder ID for nested folders

Get Group Notes

kibela_get_group_notes

Get notes in a group that aren't in any folder:

groupId (string): Group ID

Get Folder Notes

kibela_get_folder_notes

Get notes contained in a specific folder:

folderId (string): Folder ID
limit (number, optional): Number of notes to fetch (default: 100)

User Interactions

List Users

kibela_get_users

Get a list of all users with their IDs and names.

Like Note

kibela_like_note

Like a specific note:

noteId (string): Note ID

Unlike Note

kibela_unlike_note

Remove your like from a note:

noteId (string): Note ID

Using with SSE Transport

For Server-Sent Events (SSE) transport, ensure the server URL is set to:

http://localhost:3000/sse

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "kibela" '{"command":"npx","args":["-y","@kiwamizamurai/mcp-kibela-server"],"env":{"KIBELA_TEAM":"YOUR_TEAM_NAME","KIBELA_TOKEN":"YOUR_TOKEN"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "kibela": {
            "command": "npx",
            "args": [
                "-y",
                "@kiwamizamurai/mcp-kibela-server"
            ],
            "env": {
                "KIBELA_TEAM": "YOUR_TEAM_NAME",
                "KIBELA_TOKEN": "YOUR_TOKEN"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "kibela": {
            "command": "npx",
            "args": [
                "-y",
                "@kiwamizamurai/mcp-kibela-server"
            ],
            "env": {
                "KIBELA_TEAM": "YOUR_TEAM_NAME",
                "KIBELA_TOKEN": "YOUR_TOKEN"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect

Kibela MCP server