Skip to content
MCP server

Ouroboros

Spec-first layer that pins requirements and verifies results of AI coding agent work

Runs locallyActively maintainedStatus and history

The repository was last updated 7 hours ago and is published under MIT.

Pricing
Open source
Platforms
CLI, macOS, Linux
Runs
Locally
GitHub stars
6.4K
Last commit
today
Language
Python

About Ouroboros

Ouroboros is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.

Ouroboros sits alongside the coding agent you already use. It asks questions until the goal is clear, writes the answers as a spec with checkable acceptance criteria, hands the spec to the agent, and then checks the result against it.

It installs through a script, pip, Homebrew or a Claude Code plugin, and offers a browser console, a CLI and commands such as an interview and an auto mode. The README notes it runs coding agents that can change files and run commands, so permission scope matters. The code is MIT licensed.

It suits developers who want more structure and verification around agent-written code.

Install

Run in a terminal

claude mcp add ouroboros -- uvx ouroboros-ai

Add to claude_desktop_config.json

{
  "mcpServers": {
    "ouroboros": {
      "command": "uvx",
      "args": [
        "ouroboros-ai"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "ouroboros": {
      "command": "uvx",
      "args": [
        "ouroboros-ai"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "ouroboros": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "ouroboros-ai"
      ]
    }
  }
}

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

{
  "mcpServers": {
    "ouroboros": {
      "command": "uvx",
      "args": [
        "ouroboros-ai"
      ]
    }
  }
}

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

{
  "mcpServers": {
    "ouroboros": {
      "command": "uvx",
      "args": [
        "ouroboros-ai"
      ]
    }
  }
}

What it does

Requirements interview
Asks questions to remove ambiguity and reports an ambiguity score.
Pinned spec
Records acceptance criteria before the run.
Result verification
Checks output against each criterion.
Multiple hosts
Works with Claude Code, Codex and other agent tools.
Browser console
Chat interface to run interview, build and checks.
Run records
Keeps records of requirements, execution and evaluation.

Good for

  • Turn a vague idea into a testable spec
  • Verify an agent's work against acceptance criteria
  • Run a spec-driven build in Claude Code
  • Keep a record of what an agent was asked to do

Pricing

Open source

MIT licensed

Prices change. Check ouroboros.page before you buy.

Ouroboros FAQ

How do I install it?

Via an install script, pip, Homebrew, or as a Claude Code plugin.

What does it require?

The Claude Code plugin route requires Claude Code and uv; Python 3.12+ for pip.

Is it free?

The repository is MIT licensed; no pricing is listed.

Is Ouroboros free?

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

How do I add Ouroboros to Claude Code?

Run this command in your terminal: claude mcp add ouroboros -- uvx ouroboros-ai

What are the best alternatives to Ouroboros?

The closest alternatives to Ouroboros are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

Alternatives to Ouroboros

  1. REA

    MCP server

    CLI and MCP server that lets coding agents reverse engineer apps and binaries

    Runs locally
    • Open source
    • 464K GitHub stars
    • Developer tools
  2. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  3. GitHub

    MCP server

    Official MCP server connecting AI assistants to GitHub repos, issues and workflows

    Not checked yet
    • Remote
    • Open source
    • 34.5K GitHub stars
    • Developer tools
  4. MCP toolkit giving coding agents symbol-level code retrieval and editing

    Runs locally
    • Open source
    • 31.5K GitHub stars
    • Developer tools
  5. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  6. MCP server for searching the Claude Code Ultimate Guide from any MCP client

    Runs locally
    • Open source
    • 6.5K GitHub stars
    • AI models and LLM tooling