ymgeva/kanka-mcp
If you are the rightful owner of kanka-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
Kanka MCP is a Model Context Protocol server designed to interact with the Kanka API, enabling AI assistants to manage various elements of worldbuilding projects.
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
-
Clone this repository:
git clone https://github.com/yourusername/kanka_mcp.git cd kanka_mcp -
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:
- Log in to your Kanka account
- Go to "Account Settings"
- Navigate to the "API" section
- 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.
