# mindbase MCP server

> An LLM-maintained personal wiki that ingests sources, cross-references information, and writes structured markdown files on your local disk.

- Repository: https://github.com/frankchu91/mindbase
- Page: https://hostedmcp.org/servers/frankchu91/mindbase
- Transport: stdio
- Stars: 137
- License: MIT
- Latest version: 0.1.3

## Install

### Claude Code

```sh
claude mcp add mindbase -- npx -y mindbase-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "mindbase": {
      "command": "npx",
      "args": [
        "-y",
        "mindbase-mcp"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "mindbase": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mindbase-mcp"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"mindbase","type":"stdio","command":"npx","args":["-y","mindbase-mcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "mindbase": {
      "command": "npx",
      "args": [
        "-y",
        "mindbase-mcp"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add mindbase -- npx -y mindbase-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.mindbase]
command = "npx"
args = ["-y", "mindbase-mcp"]
```

### Gemini CLI

```sh
gemini mcp add -s user mindbase npx -- -y mindbase-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "mindbase": {
      "command": "npx",
      "args": [
        "-y",
        "mindbase-mcp"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `MINDBASE_DATA_DIR` | no | no | Data directory for projects and wiki files (default: ~/mindbase-data) |

## Tools (50)

- `search_wiki`: Full-text search across the user's MindBase wiki — matches page titles, one-liners, and slugs. Returns ranked list with snippets.
- `search_all_projects`: Search the user's wiki across EVERY project (not just the current one). Returns ranked matches with their owning project id, suitable for citing as `[[<project>/<slug>]]` cross-project wikilinks. Use this when answering open-ended "have I seen this before" questions or proposing cross-project bridges during ingest.
- `read_wiki_page`: Read the full content (markdown body + frontmatter + incoming/outgoing wikilinks) of a wiki page by its slug.
- `list_recent`: List wiki pages added or updated within the past N days, newest first.
- `find_related`: Find pages connected to a given page via wikilinks, shared tags, or shared sources. Returns a ranked list with the connection reason.
- `semantic_search`: Embedding-based semantic search across the wiki. Falls back to keyword search if embeddings are unavailable.
- `search_in_project`: Search the wiki, restricted to pages tagged with a specific project (uses the `project` frontmatter field).
- `ask_wiki`: Ask a natural-language question against the user's wiki. Performs graph-aware retrieval (search → top hits + their 1-hop wikilinks) and returns a cited answer using the configured LLM. Best tool for "what do I know about X?" questions. The answer text contains [N] citation markers — match each N to the corresponding entry in the citations array and render as a clickable link to mindbase_uri.
- `ingest_source`: Ingest a new source into the wiki: saves the raw text, runs LLM compile to create/update wiki pages, applies cross-linking. Returns a summary of changes.
- `ingest_plan`: Conversational ingest, step 1 of 2. Reads the source, returns the LLM's narrative takeaways and a structured plan of proposed actions — without writing anything yet. The user reviews the takeaways + plan, decides which actions to approve, and then calls ingest_execute(planId, approvals) to commit the approved subset.
- `ingest_execute`: Conversational ingest, step 2 of 2. Commits the user-approved subset of a plan returned by ingest_plan. `approvals` is a map of action id → boolean; omitted ids default to approved (true). Returns the per-action results plus a summary of what got created / updated.
- `quick_capture`: Save content to the inbox for later batch processing (NOT a direct wiki note). Use this for "save this for later, I will categorize it myself in the MindBase UI". To create a wiki note directly, use create_note instead.
- `save_chat_excerpt`: Save a fragment of the current AI conversation as a wiki page. LLM auto-titles it if no suggested_title. Marks `created_via: mcp` for audit.
- `append_to_page`: Append content to a section of an existing wiki page. Creates the section if missing. Refuses to modify human-edited pages unless force: true.
- `update_note_section`: Replace the content under a section heading on an existing page. Refuses to modify human-edited pages unless force: true.
- `tag_note`: Add or replace tags on a wiki page. mode: "add" merges with existing tags (default); "replace" overwrites.
- `set_visibility`: Set the visibility level of a wiki page. "internal" and "pii" pages are excluded from semantic search and Q&A by default.
- `list_chats`: List recent chat sessions saved in MindBase, newest first.
- `recall_chat`: Search past saved chat conversations by content. Returns matching chats with previews.
- `get_graph_insights`: Compute graph insights for the wiki: top hubs, orphans, broken links, fragmented tag clusters.
- `find_orphans`: List wiki pages with no incoming links (orphans).
- `suggest_links`: Suggest wikilinks that should be added to a specific page (review mode — does NOT modify the page).
- `run_wiki_health`: Run the full Wiki Health pipeline: build graph → generate insights → auto cross-link → L2 lint. Writes _insights.md and applies improvements.
- `export_subgraph`: Export a page + its connected neighbors (up to N hops) as a self-contained markdown bundle.
- `generate_daily_brief`: Generate a morning brief summarizing recent wiki activity with [N] citations. Default 24h lookback. Does not email — for that use the web UI Settings → Daily Brief → Send Now.
- `add_rss_feed`: Subscribe MindBase to a new RSS feed. New entries are auto-fetched every 60 minutes and compiled into wiki pages. Use this when the user says things like "subscribe me to <url>", "follow this blog", "add this to my feeds", or shares a feed URL.
- `list_feeds`: List all RSS feeds the user is subscribed to, with stats (last poll time, items ingested, errors). Use this when the user asks "what feeds am I subscribed to?" or wants to check their RSS subscriptions.
- `list_review_cards`: List spaced-repetition review cards. By default returns cards due now (due_only=true). Use this to conduct an interactive review session: list due cards, present each Q to the user, wait for their answer, call answer_card, repeat.
- `answer_card`: Submit an answer to a review card. Use ratings as: forgot (didn't know), hard (struggled), good (right answer with effort), easy (instant recall). After answering, the card is rescheduled according to SM-2.
- `create_card`: Create a new review card manually. Use this when you and the user have just discussed a fact worth remembering long-term, e.g. "add this to my reviews". The card will be scheduled for review immediately.
- `create_note`: Create a new wiki note. Use for: capturing a thought, starting a research page, or building a meeting/person/project page from a template. At least one of `title` or `content` is recommended. If `template` is given, it is filled with standard vars (date, time, slug, yesterday_slug, tomorrow_slug, title) plus any custom `variables`. Existing slugs cause an error — use append_to_page or update_note_section to extend.
- `create_daily_note`: Open or create the daily note for today (or a specific date). Daily notes follow the slug pattern `daily-YYYY-MM-DD` and are auto-linked to yesterday/tomorrow. Returns the existing page if already created, marking `created: false`.
- `mindbase_apply_template`: Overlay a schema template onto an existing project. Appends template prose to README.md and seeds template-specific sections in context.md. Idempotent — re-running with same template is a no-op marker.
- `synthesize_topic`: Synthesize what the user's wiki collectively knows about a topic. Returns structured threads with row-level citations, contradictions, and gaps. Cached; pass force_refresh: true to regenerate.
- `get_pulse`: Get today's (or a specific date's) wiki pulse: weekly writes, new connections, contradictions, stale notes, SRS due count. Use to give the user a daily situational awareness of their knowledge base.
- `find_contradictions`: Find self-contradictions in the wiki on a given topic. Returns only contradictions, no full synthesis. Useful when the user wants to reconcile evolving views.
- `find_gaps`: Find gaps in the wiki's coverage of a topic. Returns LLM-suggested missing pieces (e.g., "you mention X but never document Y").
- `mindbase_init_project`: Scaffold a new MindBase project with the v2 layout: README.md, context.md, index.yaml, sources/contributors/, sources/research/, sources/raw/, state/, logs/, artifacts/. Idempotent — refuses to overwrite existing project.
- `mindbase_load_project`: Load the README + context + index.yaml for a project (defaults to currentProjectId in config.json). Returns the three file bodies for context injection. Read-only by default; pass persist=true to also update config.json currentProjectId (i.e. switch the active project).
- `mindbase_contribute`: Append a contributor entry to the current project. Writes to sources/contributors/<user>/<YYYY-MM-DD>.md (append-only) plus log entry. Route mode forces routing: auto (LLM decides), daily (only contributor file), concept (also flag for /mb:build to extract concept), daily+concept (both).
- `mindbase_validate_structure`: Validate that a project conforms to the v2 layout. Returns list of missing required files/dirs. Used as a precondition guard by /mb:build and /mb:migrate.
- `mindbase_append_log`: Append a structured entry to logs/<today>.md. Format: ## [YYYY-MM-DD HH:MM] {operation} | {topic} | {details}
- `mindbase_gather_sources`: List contributor + research files modified since the last build (or since a given ISO date). Returns paths + sizes + mtimes. Used by /mb:build to know what to synthesize.
- `mindbase_atomic_write_context`: Write new content into context.md atomically. Steps: (1) snapshot current context.md → state/builder/snapshots/<timestamp>.md, (2) tmpwrite + rename, (3) append log entry. Enforces 400-line cap by truncating overflow to sources/research/<auto>.md.
- `mindbase_rebuild_index`: Regenerate index.yaml by scanning the project tree. Always overwrites; never partial-merges. Output schema: { project, files, contributors, sources, last_build }.
- `mindbase_status`: Project dashboard: last build time, line counts, contributor stats, recent operations, file counts. Read-only.
- `mindbase_migrate`: Migrate one or all projects from legacy wiki/ layout to v2 layout. Snapshots to archive/<projectId>-<unixTs>/ first; idempotent on re-run.
- `mindbase_ingest_file`: Ingest a file (PDF, .md, or .txt) into a project: archives the original into sources/raw/<date>/, extracts text locally (pdfjs for PDFs — no API call), writes an .extracted.md sidecar for PDFs, and returns the text. Accepts a local absolute path OR an http(s) URL that points directly at a file (e.g. an arXiv PDF link) — URLs are downloaded first. After calling this, discuss the key takeaways with the user and file a summary via mindbase_contribute.
- `mindbase_research_save`: Save research findings to sources/research/<slug>.md. Appends if file exists; otherwise creates. Always appends a log entry.
- `mindbase_export`: Export a project to a portable artifact. markdown-bundle: copies project tree to artifacts/exports/<projectId>-<timestamp>/. zip-archive: same plus zips (uses `zip` if available).

## FAQ

### Does MindBase use a vector database?

No, it is not RAG-in-a-vector-DB. It is a real markdown wiki on your disk that an LLM maintains.

### Can I use it with local models?

Yes, it is free and local by default, using a hardware-detect wizard to install the best Ollama model for your RAM.

### Does the AI edit my files without permission?

No, the AI asks before writing. Every ingest shows takeaways and a checkbox plan, and only what you approve gets written.

### Where is my data stored?

Everything is stored as plain markdown files in a local directory on your machine.
