MCP-Kanka

MCP (Model Context Protocol) server for Kanka API integration. This server provides AI assistants with tools to interact with Kanka campaigns, enabling CRUD operations on various entity types like characters, locations, organizations, and more.

This package is designed specifically to serve the needs of Teghrim but may be useful to others working with Kanka and MCP.

Features

• Entity Management: Create, read, update, and delete Kanka entities
• Search & Filter: Search entities by name with partial matching, filter by type/tags/date
• Batch Operations: Process multiple entities in a single request
• Posts Management: Create, update, and delete posts (notes) on entities
• Markdown Support: Automatic conversion between Markdown and HTML with entity mention preservation
• Type Safety: Full type hints and validation
• Client-side Filtering: Enhanced filtering beyond API limitations
• Sync Support: Efficient synchronization with timestamp tracking and Kanka’s native lastSync feature
• Timestamp Tracking: All entities include created_at and updated_at timestamps

Requirements

• Python 3.12 or higher (CI tests Python 3.12–3.15), matching python-kanka’s minimum requirement
• Kanka API token and campaign ID

Installation

From PyPI

pip install mcp-kanka

From Source (using uv)

git clone https://github.com/twistymaze/mcp-kanka.git
cd mcp-kanka
uv sync --all-groups
uv pip install -e .

From Source (using pip)

git clone https://github.com/twistymaze/mcp-kanka.git
cd mcp-kanka
pip install -e .

Quick Start

Adding to Claude Desktop

1. Set up your environment variables:

   • KANKA_TOKEN: Your Kanka API token
   • KANKA_CAMPAIGN_ID: Your campaign ID

2. Add to Claude Desktop config:

{
  "mcpServers": {
    "kanka": {
      "command": "python",
      "args": ["-m", "mcp_kanka"],
      "env": {
        "KANKA_TOKEN": "your-token",
        "KANKA_CAMPAIGN_ID": "your-campaign-id"
      }
    }
  }
}

Using with Claude Code CLI

claude mcp add kanka \
  -e KANKA_TOKEN="your-token" \
  -e KANKA_CAMPAIGN_ID="your-campaign-id" \
  -- python -m mcp_kanka

Supported Entity Types

• Character - Player characters (PCs), non-player characters (NPCs)
• Creature - Monster types, animals, non-unique creatures
• Location - Places, regions, buildings, landmarks
• Organization - Guilds, governments, cults, companies
• Race - Species, ancestries
• Note - Internal content, session digests, GM notes (private by default)
• Journal - Session summaries, narratives, chronicles
• Quest - Missions, objectives, story arcs

Available Tools (9 Total)

Entity Operations

find_entities

Search and filter entities with comprehensive options and sync metadata.

Parameters: