Skip to content
MCP server

Osiris

Context governor for coding agents: sealed task state, loop guard and payload offloading

Runs locallyActively maintainedStatus and history

The repository was last updated 12 days ago and is published under MIT.

Install
Pricing
Open source
Platforms
CLI, self-hosted, macOS
Runs
Locally
GitHub stars
2
Last commit
12 days ago
Language
Python

Similar MCP servers

About Osiris

Osiris is an open-source MCP server for ai models and llm tooling. It runs locally on your machine and is started by your AI client.

OSIRIS starts from an honest constraint: an MCP server never sees the final prompt, only what the agent sends it. So instead of editing the prompt, it produces a short deterministic manifest of about 120 tokens that the agent carries, sealed with a SHA-256 digest. On each turn the agent passes the seal back, and a mismatch reveals state drift. Separate hashes for head, plan and tail zones show whether a change breaks the prompt cache or merely appends.

Six tools cover the loop: plan, precheck, observe, recall, checkpoint and handoff. Large payloads are stored by reference and recalled with server-side grep, range, head, tail, outline, aggregate or jsonl filters so only matches reach the context. Other modules detect repeated-action loops (warn at 3, block at 5), enforce invariants from a TOML file, scrub secrets before hashing and keep a ledger of tokens, cost and savings. The tool schemas cost about 1,019 tokens.

It is local-first and independent of any model provider, stores state in SQLite under ~/.osiris, and is published on npm (osiris-mcp) and PyPI (mcp-osiris). It works alongside other MCP servers rather than replacing them.

Install

Run in a terminal

claude mcp add osiris -- npx -y osiris-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "osiris": {
      "command": "npx",
      "args": [
        "-y",
        "osiris-mcp"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "osiris": {
      "command": "npx",
      "args": [
        "-y",
        "osiris-mcp"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "osiris": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "osiris-mcp"
      ]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "osiris": {
      "command": "npx",
      "args": [
        "-y",
        "osiris-mcp"
      ]
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "osiris": {
      "command": "npx",
      "args": [
        "-y",
        "osiris-mcp"
      ]
    }
  }
}

Using several servers? Build one config file with the MCP config generator.

Configuration

  • OSIRIS_HOMERepertoire d'etat OSIRIS : base SQLite, rapports, caches. Defaut ~/.osiris.
  • OSIRIS_ROOTSRacines autorisees pour la lecture de fichiers, separees par ';'. Vide = aucune lecture de fichier.
  • OSIRIS_CACHE_TTL_STTL du cache en secondes.
  • OSIRIS_PRUNE_THRESHOLD_TOKENSSeuil de prune en tokens.
  • OSIRIS_DISPATCH_ONLY1 = n'expose que l'outil osiris.call (table d'outils stable pour le prefix cache).

Tools this server provides (6)

Taken from the project documentation; the running server may differ.

osiris.plan
Starts, updates, resumes or reports on a task and returns the sealed manifest.
osiris.precheck
Authorizes or denies an action against invariants and budget.
osiris.observe
Logs actions, detects loops and offloads large data.
osiris.recall
Rehydrates references with server-side filtering.
osiris.checkpoint
Snapshots, resumes and compacts a session.
osiris.handoff
Creates delegation contracts and structured results.

What it does

Sealed manifest
A small SHA-256-sealed state block that exposes drift.
Cache-aware hashing
Tells cache-breaking changes from harmless appends.
Server-side recall
Filters stored payloads with grep, range, outline and more.
Loop guard
Detects repeated actions and escalates from warning to block.
Invariants and budgets
Allows or denies actions based on rules and budgets.
Honest ledger
Records tokens, cost, savings and its own overhead.
Delegation contracts
Hands off tasks with executable contracts and structured results.

Good for

  • Keep a long coding task consistent across context resets
  • Cut token use from large tool outputs
  • Stop an agent repeating the same failing action
  • Hand a subtask to another agent with a clear contract

Pricing

Open source

License badge in the repository; free to run locally.

Osiris FAQ

Does it replace other MCP servers?

No. It coexists with servers such as filesystem, Git and shell and reduces what they cost in context.

Can it edit my prompt?

No. The README says an MCP server cannot see or rewrite the final prompt; it provides state the agent carries.

How many tools does it expose?

Six: plan, precheck, observe, recall, checkpoint and handoff.

Where does it keep data?

In ~/.osiris by default, set with OSIRIS_HOME, using SQLite.

Is Osiris free?

Yes. Osiris is open source, so you can use and self-host it for free.

How do I add Osiris to Claude Code?

Run this command in your terminal: claude mcp add osiris -- npx -y osiris-mcp

What are the best alternatives to Osiris?

The closest alternatives to Osiris are REA, Context7, Chrome DevTools MCP, Codebase Memory and GitHub.

Where this comes from

  • Description: written from the project's README.
  • Install steps: from the official MCP Registry entry.

How AIPoweredBot checks servers