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:

Format check (Prettier)
Lint (ESLint)
Tests (Vitest)
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