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 ofTeghrimbut may be useful to others working with Kanka and MCP.

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

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

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

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

- 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

Search and filter entities with comprehensive options and sync metadata.

- entity_type(optional): Type to filter by - character, creature, location, organization, race, note, journal, quest
- query(optional): Search term for full-text search across names and content
- name(optional): Filter by name (partial match by default, e.g., "Test" matches "Test Character")
- name_exact(optional): Use exact name matching instead of partial (default: false)
- name_fuzzy(optional): Enable fuzzy matching for typo tolerance (default: false)
- type(optional): Filter by user-defined Type field (e.g., 'NPC', 'City')
- tags(optional): Array of tags - returns entities having ALL specified tags
- date_range(optional): For journals only - filter by date range withstartandenddates
- limit(optional): Results per page (default: 25, max: 100, use 0 for all)
- page(optional): Page number for pagination (default: 1)
- include_full(optional): Include full entity details (default: true)
- last_synced(optional): ISO 8601 timestamp to get only entities modified after this time

{ "entities": [...], "sync_info": { "request_timestamp": "2024-01-01T12:00:00Z", "newest_updated_at": "2024-01-01T11:30:00Z", "total_count": 150, "returned_count": 25 } }

Create one or more entities with markdown content.

- entities: Array of entities to create, each with:

- entity_type(required): Type of entity to create
- name(required): Entity name
- entry(optional): Description in Markdown format
- type(optional): User-defined Type field (e.g., 'NPC', 'Player Character')
- tags(optional): Array of tag names
- is_hidden(optional): If true, hidden from players (admin-only)

Returns:Array of created entities with their IDs and timestamps

- updates: Array of updates, each with:

- entity_id(required): ID of entity to update
- name(required): Entity name (required by Kanka API even if unchanged)
- entry(optional): Updated content in Markdown format
- type(optional): Updated Type field
- tags(optional): Updated array of tags
- is_hidden(optional): If true, hidden from players (admin-only)

Returns:Array of results with success/error status for each update

Retrieve specific entities by ID with optional posts.

- entity_ids(required): Array of entity IDs to retrieve
- include_posts(optional): Include posts for each entity (default: false)

Returns:Array of full entity details with timestamps and optional posts

- entity_ids(required): Array of entity IDs to delete

Returns:Array of results with success/error status for each deletion

Efficiently check which entities have been modified since last sync.

- entity_ids(required): Array of entity IDs to check
- last_synced(required): ISO 8601 timestamp to check updates since

{ "modified_entity_ids": [101, 103], "deleted_entity_ids": [102], "check_timestamp": "2024-01-01T12:00:00Z" }

- posts: Array of posts to create, each with:

- entity_id(required): Entity to attach post to
- name(required): Post title
- entry(optional): Post content in Markdown format
- is_hidden(optional): If true, hidden from players (admin-only)

Returns:Array of created posts with their IDs

- updates: Array of updates, each with:

- entity_id(required): The entity ID
- post_id(required): The post ID to update
- name(required): Post title (required by API even if unchanged)
- entry(optional): Updated content in Markdown format
- is_hidden(optional): If true, hidden from players (admin-only)

Returns:Array of results with success/error status for each update

- deletions: Array of deletions, each with:

- entity_id(required): The entity ID
- post_id(required): The post ID to delete

Returns:Array of results with success/error status for each deletion

The MCP server provides enhanced search capabilities:

- Content search: Full-text search across entity names and content (client-side)
- Name filter: Exact or fuzzy name matching
- Type filter: Filter by user-defined type field (e.g., 'NPC', 'City')
- Tag filter: Filter by tags (AND logic - entity must have all specified tags)
- Date range: Filter journals by date
- Fuzzy matching: Optional fuzzy name matching for more flexible searches
- Last sync filter: Use Kanka's native lastSync parameter to get only modified entities

Note: Content search fetches all entities and searches client-side, which may be slower for large campaigns but provides comprehensive search functionality.

All entities includecreated_atandupdated_attimestamps in ISO 8601 format, enabling:

- Tracking when entities were created or last modified
- Implementing conflict resolution strategies
- Building audit trails

Thefind_entitiestool returns sync metadata including:

- request_timestamp: When the request was made
- newest_updated_at: Latest updated_at from returned entities
- total_count: Total matching entities
- returned_count: Number returned in this response

Use thelast_syncedparameter to fetch only entities modified after a specific time:

# Example: Get entities modified in the last 24 hours result = await find_entities( entity_type="character", last_synced="2024-01-01T00:00:00Z" )

Thecheck_entity_updatestool efficiently checks which entities have been modified:

# Check which of these entities have changed result = await check_entity_updates( entity_ids=[101, 102, 103], last_synced="2024-01-01T00:00:00Z" ) # Returns: modified_entity_ids, deleted_entity_ids, check_timestamp

# Clone the repository git clone https://github.com/ervwalter/mcp-kanka.git cd mcp-kanka # Install development dependencies make install

# Run all tests make test # Run with coverage make coverage # Run all checks (lint + typecheck + test) make check

# Format code make format # Run linting make lint # Run type checking make typecheck

In addition to being an MCP server, this package provides an operations layer that can be used directly in Python scripts:

from mcp_kanka.operations import create_operations # Create operations instance ops = create_operations() # Find entities result = await ops.find_entities( entity_type="character", name="Moradin" ) # Create an entity results = await ops.create_entities([{ "entity_type": "character", "name": "New Character", "type": "NPC", "entry": "A mysterious figure" }])

This makes it easy to build sync scripts, bulk operations, or other tools that interact with Kanka.

- KANKA_TOKEN: Your Kanka API token
- KANKA_CAMPAIGN_ID: The ID of your Kanka campaign

The server provides akanka://contextresource that explains Kanka's structure and capabilities.

- Initial release
- Full CRUD operations for Kanka entities
- Batch operations support
- Markdown/HTML conversion with entity mention preservation
- Sync support with timestamp tracking
- Comprehensive search and filtering capabilities

A MCP server to manage entries in Kanka platform.

Read and edit HTML/Markdown tables in GitBook-synced documents via MCP tools.

Provides read and write access to AITable.ai, a collaborative database and spreadsheet platform.

Interact with Figma files to view, comment on, and analyze designs.

Connects Sanity projects with AI tools, allowing AI models to understand content structure and perform operations using natural language.

An MCP server for Strapi CMS, providing access to content types and entries through the MCP protocol.

An MCP server for WordPress plugin audits

Perform queries and entity operations in your Fibery workspace.

Keep teams & agents coordinated automatically

A free WordPress plugin that turns your site into a governed MCP server: 153 abilities that are all off until you switch them on, bound to a least-privilege WordPress user, with every call audited.