membrian-mcp

Membrian MCP Server

MCP server for the Membrian AI OS — project memory, knowledge base, infrastructure operations.

Ships 48 tools that AI agents actually use. CRUD operations for sites, scans, findings, and compliance are available via the Membrian web UI instead.

Quick Start (npx)

No clone or install needed — run directly via npx:

{
  "mcpServers": {
    "membrian": {
      "command": "npx",
      "args": ["-y", "membrian-mcp@latest"],
      "env": {
        "MEMBRIAN_API_URL": "https://membrian.ai",
        "MEMBRIAN_API_KEY": "<your-api-key>",
        "PORT_WEB": "0"
      }
    }
  }
}

Add this to ~/.cursor/mcp.json (Cursor) or the MCP config for your client. That's it — npx downloads and runs the server automatically.

PORT_WEB: "0" disables the local web UI. Cursor spawns a separate MCP process per workspace; without this, only the first instance binds the port and the rest crash. The hosted UI is at https://membrian.ai.

MEMBRIAN_TOOLS: "lean" (optional) registers only the ~25 tools agents use day-to-day (project memory, knowledge, feedback, local-SSH workflow) instead of all 50. Fewer tool definitions = less token overhead per session. Omit or set to full for the complete toolset (graph, tunnels, curation, diary, server-side ops).

Setup (from source)

git clone <repo-url> ~/Kloner-Membrian-Mcp
cd ~/Kloner-Membrian-Mcp
npm install
npm run build  # compile TypeScript to dist/

After install, the console suggests optional next steps: install the Cursor rule and run verify. Cursor cannot attach rules automatically when you add an MCP server (by design); the rule ships in this repo and can be installed globally or copied per project.

Cursor rule + skill (strongly recommended)

The MCP tools only work well if the agent knows when to call them. This repo ships a compact rule and a detailed skill — together they give agents the right guidance at the right time without wasting context tokens.

Layering:

Layer	What it is	Loaded
Cursor rule (membrian-ai-os.mdc)	Compact always-on checklist: auto-context on task start, write-back on task end, basic principles. ~25 lines.	Every chat
MCP instructions	Tool routing guidance; sent when the MCP connects (see src/mcp-metadata.ts).	Every chat (via MCP)
Cursor skill (~/.cursor/skills/membrian/SKILL.md)	Detailed workflows: project import, knowledge extraction criteria, feedback reasons, snapshot types, quality bar. ~140 lines.	On demand

The rule handles the 90% case. The skill is loaded automatically by the agent when it needs the full decision framework (importing a project, extracting knowledge, detailed feedback, etc.).

Install	Command / action
All rules — from Membrian repo (recommended)	pnpm install-cursor-rules in the Kloner-Membrian checkout — installs all 6 shared rules to ~/.cursor/rules/
Rule only — from this MCP repo	npm run install-cursor-rule — copies membrian-ai-os.mdc to ~/.cursor/rules/
Rule — single app repo	Copy .cursor/rules/membrian-ai-os.mdc into that repo (same path)
Skill — all workspaces	Copy the membrian/ folder to ~/.cursor/skills/membrian/

Canonical source: The Membrian repo (Kloner-Membrian/.cursor/rules/) is the source of truth for all shared rules. This MCP repo ships a copy of membrian-ai-os.mdc for convenience. When updating rules, edit in the Membrian repo first, then sync here.

Restart Cursor or start a new chat after installing. The bundled rule uses alwaysApply: true.

Cursor rules vs this MCP (FAQ)

Question	Answer
Are Cursor rules part of the MCP server?	No. Rules are files under .cursor/rules/ (per repo) or ~/.cursor/rules/ (global). The MCP is a separate node …/dist/index.js process Cursor spawns. This repo ships both so you can version them together, but Cursor loads rules from disk, not from MCP.
Can this repo control rules in all my projects?	Not automatically, but close. The Membrian repo ships all shared rules at .cursor/rules/ and a one-command installer: pnpm install-cursor-rules copies them to ~/.cursor/rules/ (global — applies in every workspace). Team members pull updates and re-run the command. See docs/TEAM-SETUP.md in Kloner-Membrian for the full workflow.

Optional: company knowledge in Membrian

Repo README + Cursor rule + MCP instructions are the source of truth for this connector. Add a Membrian knowledge item (e.g. short STANDARD or PLAYBOOK) only if you want the same guidance to appear for other projects via search_knowledge without opening this repo — e.g. “Membrian MCP: pass taskDescription for context-pack intent; hybrid search uses RRF scores.” Avoid duplicating a long doc; link to internal git/docs if needed.

Verify API + credentials

Checks the same URL and API key the MCP server uses (read-only health call):

export MEMBRIAN_API_URL=https://membrian.ai   # optional if default
export MEMBRIAN_API_KEY=your-key-here
npm run verify

• Success: prints OK and the health JSON.
• Failure: wrong key, API down, or wrong URL — fix mcp.json / env to match.

In CI without API credentials, skip the check with SKIP_MEMBRIAN_VERIFY=1 npm run verify. To skip the postinstall banner, use npm install --ignore-scripts (you must run npm run build yourself).

End-to-end in Cursor: after MCP is configured, ask the agent to call the get_system_health tool (or another membrian tool). If that works, the bridge from Cursor → MCP → Membrian API is good.

Cursor MCP Config

Option A: npx (recommended — no local clone needed)

{
  "mcpServers": {
    "membrian": {
      "command": "npx",
      "args": ["-y", "membrian-mcp@latest"],
      "env": {
        "MEMBRIAN_API_URL": "https://membrian.ai",
        "MEMBRIAN_API_KEY": "<your-api-key>",
        "PORT_WEB": "0"
      }
    }
  }
}

Option B: from source (for development / local changes)

{
  "mcpServers": {
    "membrian": {
      "command": "node",
      "args": ["<path-to-repo>/dist/index.js"],
      "env": {
        "MEMBRIAN_API_URL": "https://membrian.ai",
        "MEMBRIAN_API_KEY": "<your-api-key>",
        "PORT_WEB": "0"
      }
    }
  }
}

Legacy env vars KLONER_OS_API_URL and KLONER_OS_API_KEY are still supported as fallbacks.

MCP metadata (for Cursor and other hosts)

After initialize, compliant clients receive extra server metadata (Model Context Protocol):

Field	Purpose
serverInfo.title	Human-friendly label (e.g. "Membrian — project & company memory").
serverInfo.description	Outcome-focused summary: what the bridge does, when to use it, env vars, pointer to the Cursor rule. Defined in src/mcp-metadata.ts.
instructions	Markdown guide for agents: when to use context vs search vs snapshots vs knowledge vs infra tools; non-blocking errors; pointer to membrian://docs/usage. Source: src/mcp-metadata.ts.
Resource membrian://docs/usage	Same guide as markdown; use resources/read if the host exposes resources. Listed as usage_guide.

Edit src/mcp-metadata.ts to change what models see at connection time.

Tools (40) + usage resource

Knowledge & Search (3)

• search_knowledge — hybrid (default, RRF fusion scores), keyword, or semantic search; output emphasizes rank/relevance, not raw score magnitude
• create_knowledge_item — create a pattern, playbook, standard, etc.
• update_knowledge_item — update, archive, supersede, or adjust confidence of existing items

Projects & Memory (7)

• get_project_context — full context pack; taskDescription drives API intent detection (debugging/feature/deployment/refactoring/general) and knowledge mix; maxTokens trims soft context to fit a token budget; response text includes Detected task intent when present
• list_projects — list all registered projects
• create_project — register a new project
• update_project — rename, change slug, update stack tags, or assign to a client
• draft_decision — record a project decision
• get_project_decisions — view decision log
• update_project_snapshot — create/update brief, architecture, runbook, etc.

Import (2)

• import_project — bulk import project + snapshots + decisions
• extract_patterns — bulk-create knowledge items from a project

Analytics & Maintenance (5)

• record_knowledge_feedback — ACCEPTED/REJECTED/FLAGGED feedback with reason + comment (drives nightly tier recompute)
• report_context_issue — report problems with a project's context pack (too long, stale, irrelevant, missing)
• get_system_health — overall health report
• list_stale_knowledge — find potentially outdated items
• run_staleness_check — run staleness detection

Knowledge Graph (5)

• graph_add_triple — add a temporal fact (subject → predicate → object) with optional validity dates and confidence
• graph_invalidate_triple — mark a fact as no longer valid (retained for history)
• graph_query — query entity relations with optional temporal asOf filtering
• graph_timeline — chronological timeline of facts, optionally filtered by entity
• graph_stats — entity count, triple count, and predicate distribution

Cross-Project Tunnels (2)

• discover_tunnels — find shared stack tags across projects and overlapping knowledge
• get_project_tunnels — sibling projects, shared knowledge, and decisions for a specific project

Deduplication & History (2)

• check_knowledge_duplicates — pre-flight duplicate check before creating a knowledge item
• get_snapshot_history — version history for a project snapshot type

Agent Diary (2)

• write_diary — append a diary entry for session continuity (what happened, what remains)
• read_diary — retrieve past entries to resume where a previous session left off

Project Data (3)

• set_project_data — store structured key-value pairs for a project (environments, ports, configs, service URLs)
• get_project_data — query structured data by namespace and/or key
• delete_project_data — delete structured data entries by namespace/key

Infrastructure (9)

• list_servers — list/filter servers
• create_server — register a new server for SSH operations
• update_server — change name, hostname, port, environment, notes, or client
• delete_server — remove a server and its associated data
• get_server_connection — look up a server and get a ready-to-use ssh … command prefix (the default path for interactive SSH)
• log_ssh_operation — record an SSH operation executed locally (command, exit code, stdout/stderr) for audit trail
• ssh_exec — execute ad-hoc SSH command via Membrian backend (rare — for unattended ops only)
• run_operation — logged multi-step SSH operation via backend
• get_operation_status — check operation progress

Homepage

The MCP server starts a lightweight HTTP homepage at http://localhost:4216 showing live stats, features, and a contact form. Override the port with the PORT_WEB env var (default 4216; set to 0 to disable). The web server logs to stderr (stdout is reserved for MCP stdio transport).

Development

npm run dev        # run from source via tsx
npm run build      # compile TypeScript to dist/
npm start          # run compiled dist/index.js
npm run type-check # type-check without emitting

Publishing / Releasing

Users install via npx -y membrian-mcp which pulls from npm (not git). Pushing to GitLab alone does not ship changes to users.

# 1. Bump version (patch/minor/major)
npm version patch          # commits + tags automatically

# 2. Publish to npm
npm publish                # runs `prepublishOnly` (build) first

# 3. Push commit + tag to git
git push && git push --tags

Pre-flight checklist:

• npm whoami — must be logged in (npm login if not)
• npm run build succeeds with no errors
• Version in package.json is higher than npm view membrian-mcp version

npx caching note: npx -y membrian-mcp may serve a cached version. Users can force a fresh pull with npx -y membrian-mcp@latest, or clear the npx cache (rm -rf ~/.npm/_npx). The -y flag skips the install prompt but does not guarantee the latest version is fetched.

After Pulling Changes

After pulling source changes, rebuild:

npm run build