Metadata-Version: 2.5
Name: wicked-brain-mcp
Version: 0.1.1
Summary: MCP server for Wicked Brain: a plain-markdown memory vault your AI agents can search, read and write.
Project-URL: Homepage, https://brain.wickedlabs.gg
Project-URL: Repository, https://github.com/WickedAPI/wicked-brain
Project-URL: Issues, https://github.com/WickedAPI/wicked-brain/issues
Author: SimpliFixed Technologies, LLC
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,claude,codex,markdown,mcp,memory,vault
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Requires-Dist: mcp<2,>=1.0
Requires-Dist: pyyaml>=6
Description-Content-Type: text/markdown

# wicked-brain-mcp

The MCP server for [Wicked Brain](https://github.com/WickedAPI/wicked-brain): a plain-markdown
memory vault that your AI agents can search, read and write. The vault is a folder of markdown
files on your machine. No account, no telemetry, nothing uploaded.

This package gives any MCP client the 12 vault tools (search, read, save, capture, update,
patch, move, validate, backlinks, health, and the skill list). For the slash commands, hooks and
dashboard, install the full Wicked Brain plugin for Claude Code or Codex instead.

## Run it

You need [`uv`](https://docs.astral.sh/uv/). Point the server at your vault folder:

```bash
WICKED_BRAIN_VAULT_PATH=/path/to/vault uvx wicked-brain-mcp
```

### MCP client config

```json
{
  "mcpServers": {
    "wicked-brain": {
      "command": "uvx",
      "args": ["wicked-brain-mcp"],
      "env": { "WICKED_BRAIN_VAULT_PATH": "/path/to/vault" }
    }
  }
}
```

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

```toml
[mcp_servers.wicked-brain]
command = "uvx"
args = ["wicked-brain-mcp"]
env = { WICKED_BRAIN_VAULT_PATH = "/path/to/vault" }
```

## Your vault

The vault is just a folder of markdown files. Create it anywhere and point
`WICKED_BRAIN_VAULT_PATH` at it. For free version history, make it a git repository:

```bash
mkdir ~/vault && cd ~/vault && git init
```

Wicked Brain never deletes notes and never overwrites an existing one, but git lets you review
or undo any change an agent makes.

## Tools

Read-only: `brain_search`, `brain_read_note`, `brain_validate_note`, `brain_backlinks`,
`brain_vault_health`, `brain_list_skills`, `brain_get_skill`.
Additive (never overwrite): `brain_save_note`, `brain_capture`.
Edit existing notes (destructive hint): `brain_update_note`, `brain_replace_text`, `brain_move_note`.

All tools stay inside the vault folder. See the repository for the vault layout and the
optional end-to-end-encrypted sync.

MIT licensed.
