tiddly

Tiddly MCP exposes a set of AI-friendly tools for interacting with a hosted TiddlyWiki on Node.js. The available tools allow listing tiddlers (optionally filtered), reading a specific tiddler by title, searching tiddlers by text, and creating/updating or deleting tiddlers. By default, write and delete operations are disabled (read-only mode) and must be enabled via configuration if you want to allow updates. You can connect Gemini CLI, Claude Code, Claude, or Simtheory agents to this MCP server and issue tool calls that map directly to these actions. Use the list_tiddlers tool to explore content, read_tiddler to fetch specific pages, search_tiddlers to find relevant items, and write_tiddler or delete_tiddler only if you’ve enabled write permissions for your agents.

Prerequisites:

• Node.js installed on the host running the TiddlyWiki server
• Access to the Node.js-hosted TiddlyWiki installation (server or local dev environment)
• The MCP plugin files for TiddlyWiki installed in the plugin path (e.g., tiddly-mcp folder and the $__plugins_rryan_tiddly-mcp.json tiddler)

Installation steps:

1. Install dependencies for the MCP server runtime (if using a separate server script):

# example with pnpm (as suggested by the project):
pnpm install

2. Copy the MCP plugin into your TiddlyWiki plugins directory (or import the tiddler that enables the MCP server):

- Copy the tiddly-mcp folder to your TiddlyWiki plugin path
- Import the $__plugins_rryan_tiddly-mcp.json tiddler into TiddlyWiki

3. Configure the MCP server within your environment:

# Set environment variables if needed (PORT, HOST, etc.)
export PORT=8080
export HOST=0.0.0.0

4. Start the MCP-enabled TiddlyWiki server (or run the MCP server script if you’re using a separate node process).

# Example: start your TiddlyWiki node server which includes the MCP plugin
node path/to/your-tiddlywiki-server.js

5. Verify startup by checking the logs for a line similar to: [MCP] TiddlyWiki MCP Server started on port XXXX

Note: The plugin is designed to work with server-hosted TiddlyWiki instances. If you expose this MCP server to the Internet, ensure you implement proper authentication and CORS protections as described in the plugin's documentation.

Tips and caveats:

• By default, write (write_tiddler) and delete (delete_tiddler) operations are disabled. Enable them explicitly if you need agents to modify content.
• For security, consider placing the MCP server behind a reverse proxy and require HTTP Basic authentication or other auth methods.
• If you experience connectivity issues, verify that the HOST/PORT configuration matches your deployment and that the MCP server process has network access.
• The MCP tools map directly to TiddlyWiki operations: list_tiddlers supports filter expressions, read_tiddler uses a title, and write_tiddler requires title/text (and optionally tags, type, username).
• Ensure your agents use the correct argument names when invoking tools (as listed in the README): for example, list_tiddlers with filter, limit, includeSystem, includeDetails; read_tiddler with title; etc.