Kanka MCP - Model Context Protocol Server for Kanka API

This project provides an MCP (Model Context Protocol) server for interacting with the Kanka API. It allows AI assistants to manage campaigns, characters, locations, posts, notes, and journals in your Kanka worldbuilding projects.

Features

The server provides tools for working with:
- Campaigns: List all user campaigns
- Characters: List, retrieve, create, update, and delete characters
- Locations: List, retrieve, create, update, and delete locations
- Posts: List, retrieve, create, update, and delete posts for any entity
- Notes: List, retrieve, create, update, and delete notes
- Journals: List, retrieve, create, update, and delete journals

All create and update operations properly handle HTML content for description fields and support privacy settings.

Installation

Prerequisites

- Python 3.10+

Installation

1. Clone this repository:

   git clone https://github.com/yourusername/kanka_mcp.git

   cd kanka_mcp

   

2. Install dependencies:

   pip install requests mcp[cli]

   

Or if you have a pyproject.toml file:

   pip install .

   

Configuration

You need to set the KANKA_API_KEY environment variable with your Kanka API key:

export KANKA_API_KEY=your_kanka_api_key

To get your Kanka API key:
1. Log in to your Kanka account
2. Go to "Account Settings"
3. Navigate to the "API" section
4. Create or copy your API token

Usage

Running the MCP Server

Run the server directly with:

python kanka_mcp.py

Adding to MCP Server Configuration

Add the following to your MCP server configuration:

"kanka": {
    "command": "python",
    "args": [
        "FULL_PATH_TO_SCRIPT_FOLDER/kanka_mcp.py"
    ],
    "env": {
        "KANKA_API_KEY": "YOUR_KANKA_API_KEY"
    }
}

Replace FULL_PATH_TO_SCRIPT_FOLDER with the absolute path to the directory containing the kanka_mcp.py script, and YOUR_KANKA_API_KEY with your actual Kanka API key.

Available Tools

Campaigns

- show_campaigns(): List all campaigns the user has access to.

Characters

- list_characters(campaign_id): List all characters in a campaign.
- get_character(campaign_id, character_id): Get a specific character by ID.
- create_character(campaign_id, name, ...): Create a new character.
- update_character(campaign_id, character_id, ...): Update an existing character.
- delete_character(campaign_id, character_id): Delete a character.

Locations

- list_locations(campaign_id): List all locations in a campaign.
- get_location(campaign_id, location_id): Get a specific location by ID.
- create_location(campaign_id, name, ...): Create a new location.
- update_location(campaign_id, location_id, ...): Update an existing location.
- delete_location(campaign_id, location_id): Delete a location.

Posts

- list_posts(campaign_id, entity_id): List all posts for an entity.
- get_post(campaign_id, entity_id, post_id): Get a specific post by ID.
- create_post(campaign_id, entity_id, name, ...): Create a new post.
- update_post(campaign_id, entity_id, post_id, ...): Update an existing post.
- delete_post(campaign_id, entity_id, post_id): Delete a post.

Notes

- list_notes(campaign_id): List all notes in a campaign.
- get_note(campaign_id, note_id): Get a specific note by ID.
- create_note(campaign_id, name, ...): Create a new note.
- update_note(campaign_id, note_id, ...): Update an existing note.
- delete_note(campaign_id, note_id): Delete a note.

Journals

- list_journals(campaign_id): List all journals in a campaign.
- get_journal(campaign_id, journal_id): Get a specific journal by ID.
- create_journal(campaign_id, name, ...): Create a new journal.
- update_journal(campaign_id, journal_id, ...): Update an existing journal.
- delete_journal(campaign_id, journal_id): Delete a journal.

License

This project is licensed under the terms specified in the LICENSE file.