nucleus — Claude Code MCP server: what it does, how to install
Maintains agent decisions and project context inside a local .brain folder. It links memory across coding editors without vector databases.
claude mcp add --transport http nucleus https://relay.nucleusos.dev/mcpWhat nucleus does
Nucleus stores project policies and architecture decisions inside plain markdown and JSON files within a repository directory named .brain. Agents read this directory through MCP tools. This avoids re-explaining previous technical trade-offs at the start of every session.
The package bundles 30 tools and a local utility called nucleus-rabbithole that tracks task focus using SQLite without background daemons. Its verification loops handle syntax, tests, and human feedback to capture deltas between intent and actual output.
You need Python 3.10 or newer. Python versions 3.11 through 3.13 install clean binary wheels, whereas 3.14 compiles dependencies like watchdog from source. The remote endpoint remains offline pending review. When running nucleus build, an authenticated claude, devin, or agy CLI binary must exist on PATH, or the process stops at the planning step.
What it helps with
- retain architectural decisions across multiple coding sessions
- verify AI code output against syntax and runtime checks
- prevent context loss when switching between different IDEs
- track subtask rabbit holes with a local push-down stack
Example prompts for the agent
- Record the new database migration policy into the
.brainlog - Run
nucleus reviewon the latest changes to capture our verdict - Check subtask depth using
nucleus-rabbithole
How to install nucleus
1Platform CLI: remote server
claude mcp add --transport http nucleus https://relay.nucleusos.dev/mcp2Platform CLI
claude mcp add --env NUCLEUS_BRAIN_PATH=<NUCLEUS_BRAIN_PATH> --transport stdio nucleus -- uvx nucleus-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from nucleus-mcp <command>
1Platform CLI: remote server
codex mcp add nucleus --url https://relay.nucleusos.dev/mcp2Platform CLI
codex mcp add nucleus --env NUCLEUS_BRAIN_PATH=<NUCLEUS_BRAIN_PATH> -- uvx nucleus-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from nucleus-mcp <command>
Config file
{
"mcpServers": {
"nucleus": {
"url": "https://relay.nucleusos.dev/mcp"
}
}
}{
"mcpServers": {
"nucleus": {
"command": "uvx",
"args": [
"nucleus-mcp"
],
"env": {
"NUCLEUS_BRAIN_PATH": "<NUCLEUS_BRAIN_PATH>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from nucleus-mcp <command>
Config file
{
"servers": {
"nucleus": {
"type": "http",
"url": "https://relay.nucleusos.dev/mcp"
}
}
}{
"servers": {
"nucleus": {
"type": "stdio",
"command": "uvx",
"args": [
"nucleus-mcp"
],
"env": {
"NUCLEUS_BRAIN_PATH": "<NUCLEUS_BRAIN_PATH>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from nucleus-mcp <command>
1Platform CLI: remote server
gemini mcp add -t http nucleus https://relay.nucleusos.dev/mcp2Platform CLI
gemini mcp add -e NUCLEUS_BRAIN_PATH=<NUCLEUS_BRAIN_PATH> nucleus uvx nucleus-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from nucleus-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about nucleus
How to install nucleus in Claude Code?
Run claude mcp add --env NUCLEUS_BRAIN_PATH=<NUCLEUS_BRAIN_PATH> --transport stdio nucleus -- uvx nucleus-mcp in your terminal.
What does nucleus do?
It provides persistent memory for AI tools by keeping decisions and task states in a local .brain directory. This allows different coding clients to read the same project context.
What dependencies does nucleus build require?
It requires an authorized CLI tool on your system PATH, such as claude, devin, or agy. Without an active login on one of these binaries, code generation will halt after creating the plan.
