# Tiddly MCP
Tiddly MCP is a [Model Context Protocol](https://modelcontextprotocol.io/)
plugin for [TiddlyWiki](https://tiddlywiki.com/) that lets you connect AI agents
to your TiddlyWiki.
**WARNING:** This plugin is a work in progress.
This plugin is tested and works with:
* [Gemini CLI](https://geminicli.com/)
* [Claude Code](https://code.claude.com/docs/en/overview)
* [Claude](https://claude.ai/)
* [Simtheory](https://simtheory.ai/)
The plugin only supports server (Node.JS-hosted) versions of TiddlyWiki.
This plugin provides the following tools to AI agents via MCP:
| Name | Description | Arguments |
| ---- | ----------- | --------- |
| `list_tiddlers` | List all tiddlers or filter them using a [filter expression](https://tiddlywiki.com/static/Filters.html). | `filter`, `limit`, `includeSystem` |
| `filter_tiddlers` | Filter tiddlers using a [filter expression](https://tiddlywiki.com/static/Filters.html). | `filter`, `includeDetails` |
| `read_tiddler` | Read a tiddler by title. | `title` |
| `search_tiddlers` | Search for tiddlers containing specific text. | `query`, `field`, `caseSensitive` |
| `write_tiddler` | Create or update a tiddler by title. | `title`, `text`, `tags`, `type`, `username` |
| `delete_tiddler` | Deletes a tiddler by title. | `title` |
The plugin defaults to **read only** mode. The update and delete tiddler tools are off by default.
# Installation
**This plugin only works with server (hosted on Node.JS) TiddlyWikis.**
1. Drag and drop `tiddly-mcp.json` into your **Node.JS-hosted** TiddlyWiki.
1. Import the tiddler into your wiki.
1. Open the plugin configuration and customize the port and other settings.
## Authentication
**For now, we recommend not exposing this MCP server to the Internet and recommend using the plugin locally with Gemini CLI, Claude Code, or Claude Desktop.**
If you want to expose this the open web, we recommend:
* Set it up behind a reverse proxy, just like your Node.JS-hosted TiddlyWik is.
* Use HTTP Basic Authentication to protect access. Most clients support custom
headers that allow you to provide a `Authentication: Basic asdf1234`
authentication header.
* Set the CORS allowed hosts to the domain name you are hosting it on.
* Use a path other than `https://mydomain.com/mcp` to prevent casual domain scanning for MCP servers.
# Testing
To run the tests locally:
```bash
pnpm run test
```
# Acknowledgements
* This plugin was initially authored by Claude Code and Gemini CLI.
* Thanks to https://github.com/tiddly-gittly/Modern.TiddlyDev for the nice
TypeScript starter kit for TiddlyWiki plugin development.
