Brainy MCP server
Commit Oct 7, 2026Provides a shared knowledge base and task queue to enable safe collaboration and coordination between multiple AI agents.
Also known as memokar/brainy
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.2.0
- Last commit
- Oct 7, 2026
- License
- AGPL-3.0
What is Brainy MCP?
Brainy provides a shared knowledge base and task queue to enable safe collaboration and coordination between multiple AI agents.
Summary generated from the project's README
About Brainy MCP server
Brainy serves as a centralized coordination layer for multiple AI agents, such as Claude and ChatGPT, to work together without overwriting each other. It functions as a self-hosted backbone that provides a shared knowledge base and a task queue through a single MCP endpoint. Developers can connect local clients via stdio or remote connectors using OAuth 2.1 and service tokens. The system uses plain Markdown files stored in a Git repository to ensure every knowledge update has a versioned history and rollback capability.
To prevent conflicts, the server implements atomic task claims and resource leases, ensuring only one agent processes a specific task or file area at a time. It includes built-in safety features like per-space access control lists, secret detection, and an append-only audit log. Users can manage the system through a web admin UI or approve proposed changes via Telegram. The entire application is built using the Python standard library and SQLite, requiring no external dependencies for installation.
What you can do with it
- 1Coordinate multi-agent task handoffsAssign a task to one agent and have another agent claim and complete it once it is ready.
- 2Prevent concurrent file editsUse resource claims to reserve specific code paths so multiple agents do not edit the same files simultaneously.
- 3Implement human-in-the-loop approvalsRequire a person to review and approve knowledge updates proposed by an AI before they are committed to the repository.
- 4Maintain a secure audit trailTrack every read, claim, and write operation performed by different agents for security and debugging.
Written from the project's README. Every use case is checked against a quote from it.
How to install Brainy MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Brainy MCP in Claude Code
$ claude mcp add brainy -- docker run -i --rm ghcr.io/memokar/brainy:0.2.0Install Brainy MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"brainy": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/memokar/brainy:0.2.0"
]
}
}
}Install Brainy MCP in VS Code
.vscode/mcp.json
{
"servers": {
"brainy": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/memokar/brainy:0.2.0"
]
}
}
}Install Brainy MCP in VS Code CLI
$ code --add-mcp '{"name":"brainy","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/memokar/brainy:0.2.0"]}'Install Brainy MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"brainy": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/memokar/brainy:0.2.0"
]
}
}
}Install Brainy MCP in Codex
$ codex mcp add brainy -- docker run -i --rm ghcr.io/memokar/brainy:0.2.0Install Brainy MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.brainy] command = "docker" args = ["run", "-i", "--rm", "ghcr.io/memokar/brainy:0.2.0"]
Install Brainy MCP in Gemini CLI
$ gemini mcp add -s user brainy docker -- run -i --rm ghcr.io/memokar/brainy:0.2.0Install Brainy MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"brainy": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/memokar/brainy:0.2.0"
]
}
}
}Configuration
BRAINY_DB_PATHBRAINY_KNOWLEDGE_ROOTBRAINY_TOKENBRAINY_WEB_SESSION_KEY
| Name | Description | |
|---|---|---|
| BRAINY_DB_PATH | — | |
| BRAINY_KNOWLEDGE_ROOT | — | |
| BRAINY_TOKEN | — | |
| BRAINY_WEB_SESSION_KEY | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablememokar/brainy is public and reachablegithub.com/memokar/brainy ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)AGPL-3.0spdx.org/licenses/AGPL-3.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-07github.com/memokar/brainy ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubBrainy
A shared brain for your AI agents — and for the humans who work with them.
Brainy is a self-hosted knowledge and task backbone that Claude, ChatGPT and any other MCP-capable AI connect to through one controlled endpoint. Every agent reads the same knowledge, works on the same task list and leaves an audit trail — so your AIs can hand work to each other instead of living in separate chat silos.
ChatGPT ─┐ ┌─ Git-versioned knowledge (Markdown)
Claude ─┼──► MCP endpoint ──► Brainy ───┼─ Tasks with atomic claim/lease
Your bot ┘ (OAuth / tokens) ACL+Audit └─ Spaces, roles, append-only audit log
▲
Humans: web admin UI (+ optional Telegram approvals)
Why Brainy?
- AIs that collaborate. ChatGPT creates a task, Claude claims it, does the work and writes the result back; a human reviews. Coordination happens through tasks — no hidden agent-to-agent magic.
- One source of truth. Knowledge lives as plain Markdown in a Git repository. Every write is a commit, so you get history, diffs and rollback for free.
- Safe by default. No shell, no filesystem, no eval over MCP. Path allowlist, per-space ACLs, secret detection on writes, rate limits, hashed tokens and an append-only audit log.
- No double work. Atomic task claims with leases and claim tokens guarantee that two agents never process the same task at the same time.
- Human in the loop. Agents can propose knowledge changes; a human approves or rejects them (web UI or Telegram). Tasks can require review/approval before they count as done.
- Zero dependencies. Pure Python standard library + SQLite. No pip install, tiny attack surface.
Why not just a markdown file?
A shared notes file in a Git repo is a great knowledge store — and Brainy keeps that part on purpose: knowledge is plain Markdown in Git, with history, diff and rollback. The problem is everything a bare file doesn't do once more than one agent touches it:
- Two agents overwrite each other. Nothing serializes concurrent writes to the same file.
Brainy writes go through optimistic concurrency (
expected_git_commit) plus a server-side write lock: exactly one writer commits, the others get aConflictand re-read — no lost edits. - No task hand-off. A file can list TODOs, but it can't stop two agents from grabbing the same
one. Brainy tasks use an atomic claim (
UPDATE ... WHERE status='READY', one row): exactly one agent wins, the rest get a conflict and move on. - No per-area permissions. A file is all-or-nothing. Brainy has Spaces with per-space ACLs, so an agent only reads/writes the areas you grant it.
- No approval step. Agents can propose changes for a human to approve (web UI or Telegram) instead of writing straight to the source of truth.
- "Who changed what?" beyond
git blame. Every action — reads of task state, claims, writes, rejections — lands in an append-only audit log enforced by a DB trigger.
Both guarantees above are covered by a concurrency test
(tests/test_concurrency.py): 20 threads racing on one task yield
exactly 1 winner and 19 conflicts, and 20 threads writing the same file yield exactly 1
commit and 19 conflicts, with the repo left clean.
How is Brainy different?
Honest comparison with the tools people mention most. Beads is closest to Brainy's task side, and Central Brain to its knowledge side; neither is a one-to-one match. Facts are from each project's own docs (links below); where something isn't documented, it says so rather than guessing.
| Brainy | Beads 1 | Central Brain 2 | Shared notes file | |
|---|---|---|---|---|
| What it is | Knowledge base + task queue | AI-agent issue/task tracker | AI memory layer | Markdown in a repo |
| Knowledge store | Markdown in Git | — (issue tracker) | Plain files + local vector index | Markdown in Git |
| Task queue with atomic claims | ✅ | ✅ | not documented | ❌ |
| Per-area permissions (ACL) | ✅ Spaces/roles | ❌ | ❌ | ❌ |
| Append-only audit log | ✅ (DB-enforced) | partial (Git/DB history) | ❌ | git blame only |
| Human approval for writes | ✅ (web/Telegram) | ❌ | ❌ | ❌ |
| MCP server | ✅ | ✅ | ✅ | ❌ |
| Multi-agent concurrency control | ✅ claims + write lock | ✅ claims + concurrent writers | not documented | ❌ |
| Dependencies | none (stdlib + SQLite) | bundles Dolt (Go) | bundles embedding model | n/a |
| Self-hosted | ✅ | ✅ | ✅ (cloud optional) | ✅ |
| License | AGPL-3.0 (+ commercial) | MIT | proprietary | n/a |
Features
| Area | What you get |
|---|---|
| Knowledge | list_documents, get_document, search_knowledge, write_document (optimistic concurrency via Git commit), append_document, propose_write |
| Tasks | create_task, claim_task, renew_claim, complete_task, fail_task, release_task, dependencies, priorities, review/approve/reject |
| Resource claims | claim_resource, renew_resource, release_resource, list_resource_claims — reserve any resource (a free-form key per space, e.g. a file path or area) with an atomic lease, same model as task claims |
| Access | Spaces (tenants/areas), roles ADMIN / EDITOR / AGENT / READER, per-space ACL, service tokens, OAuth 2.1 (for Claude/ChatGPT remote connectors) |
| Operations | Web admin UI, audit log, agent registry + dispatcher framework, backup & verified restore scripts |
Quickstart (Docker)
Try it in one command — no clone, no setup. Runs a throwaway demo (temporary database + example knowledge, deleted on exit) as an MCP stdio server:
docker run --rm -i ghcr.io/memokar/brainy:latest --demo
For a real install, run the server (prebuilt image, published on every release):
docker run -d --name brainy -p 127.0.0.1:8765:8765 -v brainy-data:/data ghcr.io/memokar/brainy:latest
docker logs brainy # prints your one-time ADMIN token on first start
Or build it yourself with Compose:
git clone https://github.com/memokar/brainy.git
cd brainy
docker compose up -d
docker compose logs brainy # prints your one-time ADMIN token on first start
Brainy now listens on http://127.0.0.1:8765 (MCP endpoint: /mcp, admin UI: /admin — log in
with the token). For remote AI connectors put it behind HTTPS (see
deploy/nginx-brainy.conf.example) and set BRAINY_PUBLIC_BASE_URL.
Quickstart (bare metal, Linux, Python ≥ 3.10)
export BRAINY_DB_PATH=$PWD/data/brainy.db
export BRAINY_KNOWLEDGE_ROOT=$PWD/data/knowledge
export BRAINY_WEB_SESSION_KEY=$PWD/data/web_session.key
cp -r examples/knowledge "$BRAINY_KNOWLEDGE_ROOT"
git -C "$BRAINY_KNOWLEDGE_ROOT" init -q && git -C "$BRAINY_KNOWLEDGE_ROOT" add -A \
&& git -C "$BRAINY_KNOWLEDGE_ROOT" commit -qm "initial knowledge"
python3 scripts/bootstrap.py "$BRAINY_DB_PATH" --with-token # prints ADMIN token once
python3 scripts/init_prod_db.py "$BRAINY_DB_PATH" # seeds default spaces
python3 scripts/serve.py
Connecting an AI
- Claude Code:
claude mcp add --transport http brainy http://127.0.0.1:8765/mcp --header "Authorization: Bearer <token>" - Local stdio clients (e.g. Claude Desktop): run Brainy as a subprocess:
Try it without any setup:{"mcpServers": {"brainy": {"command": "python3", "args": ["/opt/brainy/scripts/stdio.py"], "env": {"BRAINY_DB_PATH": "/var/lib/brainy/brainy.db", "BRAINY_KNOWLEDGE_ROOT": "/opt/brainy-knowledge", "BRAINY_TOKEN": "<token>"}}}}python3 scripts/stdio.py --demo(temporary data, deleted on exit). - Any other MCP client with custom headers: endpoint
https://<your-host>/mcp, headerAuthorization: Bearer <service token>. - Claude.ai / ChatGPT remote connectors: use the OAuth 2.1 flow (discovery at
/.well-known/oauth-authorization-server). SetBRAINY_PUBLIC_BASE_URLto your HTTPS URL.
Brainy is listed in the official MCP Registry as
io.github.memokar/brainy.
Give each AI its own principal (e.g. claude, chatgpt) with role AGENT and only the spaces it
needs. Every action then shows up in the audit log under that name.
Example: two coding agents in one repo
Two agents working the same repository can step on each other's files. With resource claims each one reserves the area it's about to touch — a free-form key per space — and the other backs off until it's released or the lease expires:
// Agent A, before editing the auth code:
claim_resource { "space": "shared", "resource_key": "repo:app/src/auth/**", "lease_seconds": 1800 }
// -> { "claim_token": "…", "lease_until": "…" } A now owns that area
// Agent B, about to touch the same area:
claim_resource { "space": "shared", "resource_key": "repo:app/src/auth/**" }
// -> Conflict: already claimed → B picks a different area (e.g. "repo:app/src/api/**")
renew_resource { "space": "shared", "resource_key": "repo:app/src/auth/**", "claim_token": "…" } // A keeps working
release_resource { "space": "shared", "resource_key": "repo:app/src/auth/**", "claim_token": "…" } // A done → free again
list_resource_claims { "space": "shared" } // who holds what right now
Same guarantee as task claims — exactly one holder at a time, expired leases free up automatically
(see tests/test_resources.py). Resource claims reuse the task
permissions/scopes (can_claim_tasks / brainy:tasks:write), so any agent that can claim tasks can
claim resources.
Configuration
All configuration comes from environment variables — see .env.example.
Secrets (tokens, keys) are never stored in the repository or the knowledge base.
Extensions
The core ships a worker plugin interface and a deterministic MockWorker. Real workers that let
agents execute tasks autonomously (e.g. Claude Code, Codex) are separate extensions loaded via
BRAINY_WORKER_PLUGINS. See docs/extensions.md.
Running the tests
for t in tests/test_*.py; do python3 "$t" || exit 1; done
Status & roadmap
Brainy runs in production for its author. Current limitations:
- Code comments are still partly German; all user-facing text is English.
- Single-node design (SQLite). PostgreSQL only if real multi-writer load appears.
License
Copyright (C) 2026 Mehmet Karakolcu
Brainy is dual-licensed:
- Open source: GNU AGPL-3.0. Free for everyone, including companies — but if you modify Brainy and offer it to others (also as a network service), you must publish your changes under the AGPL.
- Commercial license: for companies that want to use or embed Brainy without AGPL obligations. See COMMERCIAL.md.
Contributions require agreeing to the Contributor License Agreement.
Footnotes
-
Beads — https://github.com/steveyegge/beads (MIT, Go; stores issues in Dolt, a version-controlled SQL database; earlier versions used SQLite + JSONL). ↩
-
Central Brain by NeuroAIgent — https://neuroaigent.ai (local-first AI memory, Windows + Apple-silicon macOS, MCP integration; pricing per the site at time of writing: $12/mo solo, $35/mo for 4 licenses). ↩
Brainy MCP questions
How do I add Brainy MCP to Claude Code?
Run claude mcp add brainy -- docker run -i --rm ghcr.io/memokar/brainy:0.2.0 in your terminal. Add --scope user to make it available in every project.
How do I add Brainy MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How does Brainy prevent multiple agents from working on the same task?
It uses atomic task claims with leases and claim tokens to ensure exactly one agent wins a task while others receive a conflict.
Where is the knowledge stored?
Knowledge is stored as plain Markdown files within a Git repository, providing history and rollback capabilities.
Can humans review changes made by AI agents?
Yes, agents can propose knowledge changes which a human can then approve or reject via a web UI or Telegram.
Does Brainy require many dependencies to run?
No, it is built using the pure Python standard library and SQLite, resulting in a tiny attack surface.