TiddlyWiki MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to TiddlyWiki wikis via the HTTP API. Supports semantic search using Ollama embeddings.

Features

MCP Tools

• search_tiddlers - Search tiddlers using TiddlyWiki filter syntax, semantic similarity, or hybrid (both combined)
• create_tiddler - Create new tiddlers with custom fields
• update_tiddler - Update existing tiddlers with diff preview
• delete_tiddler - Delete tiddlers with content preview

MCP Resources

• filter-reference://syntax - Complete TiddlyWiki filter syntax reference

Semantic Search

When Ollama is available, the server provides semantic search capabilities:

• Natural language queries find conceptually related tiddlers
• Uses nomic-embed-text embeddings model
• SQLite-vec for efficient vector similarity search
• Background sync keeps embeddings up-to-date
• Hybrid mode combines filter results with semantic reranking

Requirements

• Node.js 22+
• TiddlyWiki with HTTP API enabled (e.g., TiddlyWiki on Node.js with listen command)
• Ollama (optional, for semantic search)

Build Prerequisites

This project uses native SQLite modules that require compilation. You'll need:

• Linux: build-essential, Python 3
• macOS: Xcode Command Line Tools (xcode-select --install)
• Windows: Visual Studio Build Tools, Python 3

Installation

From npm (recommended)

TIDDLYWIKI_URL=http://localhost:8080 npx tiddlywiki-mcp-server

Or install globally:

npm install -g tiddlywiki-mcp-server
TIDDLYWIKI_URL=http://localhost:8080 tiddlywiki-mcp-server

From source

git clone https://github.com/ppetru/tiddlywiki-mcp.git
cd tiddlywiki-mcp
npm install
npm run build

Quick Start

1. Start TiddlyWiki with HTTP API

# Install TiddlyWiki if you haven't already
npm install -g tiddlywiki

# Create a new wiki and start it with HTTP API
tiddlywiki mywiki --init server
tiddlywiki mywiki --listen port=8080

2. (Optional) Set up Ollama for Semantic Search

# Install Ollama from https://ollama.ai
# Then pull the embedding model:
ollama pull nomic-embed-text

3. Start the MCP Server

TIDDLYWIKI_URL=http://localhost:8080 npx tiddlywiki-mcp-server

Configuration

All configuration is via environment variables. See .env.example for a complete reference.

Required

Variable	Description
TIDDLYWIKI_URL	URL of your TiddlyWiki server (e.g., http://localhost:8080)

Optional

Variable	Default	Description
MCP_TRANSPORT	stdio	Transport mode: stdio or http
MCP_PORT	3000	HTTP server port (when using http transport)
OLLAMA_URL	http://localhost:11434	Ollama API URL
OLLAMA_MODEL	nomic-embed-text	Embedding model name
EMBEDDINGS_ENABLED	true	Enable/disable semantic search
EMBEDDINGS_DB_PATH	./embeddings.db	SQLite database path for embeddings
AUTH_HEADER	X-Oidc-Username	HTTP header for authentication (can be any header your TiddlyWiki expects)
AUTH_USER	mcp-user	Username for TiddlyWiki API requests

Usage

stdio Mode (Claude Desktop)

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "tiddlywiki": {
      "command": "npx",
      "args": ["tiddlywiki-mcp-server"],
      "env": {
        "TIDDLYWIKI_URL": "http://localhost:8080"
      }
    }
  }
}

HTTP Mode

Start the server:

TIDDLYWIKI_URL=http://localhost:8080 MCP_TRANSPORT=http MCP_PORT=3000 npx tiddlywiki-mcp-server

The server exposes:

• GET /health - Health check endpoint
• POST /mcp - MCP JSON-RPC endpoint (stateless mode)

Example Tool Usage

Filter search (TiddlyWiki filter syntax):

{
  "name": "search_tiddlers",
  "arguments": {
    "filter": "[tag[Journal]prefix[2025-01]]",
    "includeText": true
  }
}

Semantic search (natural language):

{
  "name": "search_tiddlers",
  "arguments": {
    "semantic": "times I felt anxious about work",
    "limit": 10
  }
}

Hybrid search (filter + semantic reranking):

{
  "name": "search_tiddlers",
  "arguments": {
    "filter": "[tag[Journal]]",
    "semantic": "productivity tips",
    "limit": 20
  }
}

Development

Setup

npm install

Running Tests

npm test

Tests run quickly (~1s) and include unit tests for all tool handlers.

Linting

npm run lint        # Check for issues
npm run format      # Fix formatting
npm run format:check # Check formatting only

Type Checking

npm run typecheck

Pre-commit Hooks

Pre-commit hooks are configured with lefthook and run automatically:

1. Format check (Prettier)
2. Lint (ESLint)
3. Tests (Vitest)
4. Type check (TypeScript)

Building

npm run build

Architecture

src/
├── index.ts              # Entry point, transport setup, server lifecycle
├── tiddlywiki-http.ts    # TiddlyWiki HTTP API client
├── service-discovery.ts  # URL resolution (direct URLs, Consul SRV, hostname:port)
├── filter-reference.ts   # Filter syntax documentation
├── logger.ts             # Structured logging
├── tools/                # MCP tool handlers
│   ├── types.ts          # Shared types and Zod schemas
│   ├── search-tiddlers.ts
│   ├── create-tiddler.ts
│   ├── update-tiddler.ts
│   └── delete-tiddler.ts
└── embeddings/           # Semantic search infrastructure
    ├── database.ts       # SQLite-vec database
    ├── ollama-client.ts  # Ollama API client
    └── sync-worker.ts    # Background embedding sync

Key Design Decisions

• Stateless HTTP mode: Each request gets its own Server/Transport instance to prevent request ID collisions with concurrent clients
• Graceful degradation: Semantic search is optional; the server works without Ollama
• Token-aware responses: Search results are validated against token limits with pagination suggestions
• Background sync: Embeddings are updated periodically without blocking requests

License

MIT