memoo-mcp

Memoo MCP server — knowledge graph RAG over the Memoo REST API, for Cursor, Claude, Codex, and other MCP hosts.

Auth: API key only (moo_sk…). No JWT. No OAuth.

npx -y memoo-mcp@latest --version

Quick start

1. Get a Memoo API key (moo_sk…) and a namespace (UUID or name).

2. Add this to your MCP config (Cursor example — same shape works for Claude Desktop / Codex):

{
  "mcpServers": {
    "memoo": {
      "command": "npx",
      "args": ["-y", "memoo-mcp@latest"],
      "env": {
        "MEMOO_API_KEY": "moo_sk_xxx",
        "MEMOO_NAMESPACE": "your-namespace",
        "MEMOO_BASE_URL": "https://memoo.hinha.web.id",
        "MEMOO_TIMEOUT": "600s"
      }
    }
  }
}

3. Restart the host. Tools like memoo_search and memoo_ask should appear.

That is enough for most users.

Related MCP server: Crosmos MCP Server

Install options

Check / update the CLI:

memoo-mcp --version          # or: memoo-mcp version
memoo-mcp update             # checks npm only — does not auto-install
memoo-mcp --help

If update reports a newer version:

npm i -g memoo-mcp@latest
# or keep using npx -y memoo-mcp@latest

CLI

Flags / env

HTTP-only: MEMOO_HOST / MEMOO_PORT (default 127.0.0.1:8787). Path is fixed at /mcp. Optional MEMOO_ALLOWED_ORIGINS (comma-separated) for CORS.

Local from source

make install && make check && make build
make stdio ARGS='--memo-namespace <uuid|name> --timeout 600s'
# needs MEMOO_API_KEY in env or .env

Copy .env.example → .env for local development.

Host compatibility

Primary transport is stdio. Same command + args + env pattern as other MCP servers.

Path-based local install (instead of npx):

{
  "mcpServers": {
    "memoo": {
      "command": "node",
      "args": [
        "/absolute/path/to/memoo-mcp/dist/index.js",
        "--memoo-base-url",
        "https://memoo.hinha.web.id",
        "--memo-namespace",
        "your-namespace",
        "--timeout",
        "600s"
      ],
      "env": {
        "MEMOO_API_KEY": "moo_sk_xxx"
      }
    }
  }
}

Namespace resolution

--memo-namespace / MEMOO_NAMESPACE accepts a UUID or name.

On stdio boot the server calls GET /api/v1/namespaces/{id} (detail), resolves the canonical name, and uses that as the tool default. It does not list all namespaces for setup.

When a default is set, agents should omit namespace on tools and should not call memoo_list_namespaces unless you ask to switch or list other namespaces.

Tools

Resources

• memoo://namespaces

• memoo://health

• memoo://episodes/{namespace}/{id}

• memoo://docs/workflow / memoo://docs/instructions

HTTP serve

npm run serve
# or: memoo-mcp serve

• MCP: http://127.0.0.1:8787/mcp

• Health: GET /health

• Auth: Authorization: Bearer moo_sk… (or process MEMOO_API_KEY)

Skills

MCP tools and skills are separate. The skill teaches the agent when/how to explore; the server only registers tools.

Shipped skill: skills/exploring-knowledge-graph/SKILL.md
Slash name: /exploring-knowledge-graph

Copy into your host skills directory (Claude / Cursor / .agents/skills), with Memoo MCP enabled. See the skill file for the exploration format.

Developers

make check          # typecheck + biome + tests (coverage fail <75%, warn <90%)
make test-coverage
make release VERSION=1.0.1   # bump package.json, commit, create annotated tag v1.0.1
git push && git push origin v1.0.1   # triggers GitHub Actions → npm publish

Coverage policy: CI fails below 75% (lines/statements/functions/branches). Below 90% emits a warning annotation only.

Release: git tag vX.Y.Z is the source of truth. The release workflow syncs package.json version from the tag, runs checks, then npm publish. Requires repo secret NPM_TOKEN.

This package is the canonical Memoo MCP implementation. The Go gateway in the Memoo monorepo (@hinha/memoo) is deprecated for new installs.

Docs

• OPERATOR.md

• SECURITY.md

License

MIT