home / mcp / scribe mcp server

Scribe MCP Server

Scribe is a documentation governance system designed to keep AI agents aligned, accountable, and auditable while they build software. In short: Scribe is the guardrails. Agents still drive—but they don’t get to veer into the ditch, rewrite history, or pretend unfinished work is done

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "cortalabs-scribe_mcp": {
      "command": "bash",
      "args": [
        "-lc",
        "cd /home/path/to/scribe_mcp && exec scribe-server"
      ],
      "env": {
        "REPO_ROOT": "<REPO_ROOT_PATH>",
        "SCRIBE_ROOT": "<SCRIBE_ROOT_PATH>",
        "SCRIBE_DB_URL": "<POSTGRES_OR_SQLITE_URL>",
        "SCRIBE_POSTGRES_SCHEMA": "scribe",
        "SCRIBE_STORAGE_BACKEND": "sqlite"
      }
    }
  }
}

You are equipped with a robust MCP server that enables AI agents and developers to log, organize, and audit project documentation with templates, cross-project search, and structured workflows. It provides zero-config storage, atomic operations, and a suite of tools to manage docs, read code, and monitor project lifecycles in an auditable, production-ready way.

How to use

Access the MCP server through an MCP client to register projects, log progress, manage documentation, and run intelligent file operations. You will register a project, append entries for milestones or tasks, and periodically run doc updates to keep architecture guides, phase plans, checklists, and progress logs in sync with implementation.

Typical usage patterns include: setting the active project context, appending progress entries (or bulk logs), applying atomic doc updates via the manage_docs suite, and reading files or code intelligence to understand large codebases without loading full content. You also get reminders about stale documentation and drift between plans and implementation, with configurable cooldowns per repository and agent.

How to install

Prerequisites: you need Python 3.11 or newer and a standard Python package manager. Optional PostgreSQL is available for production deployments; SQLite works out of the box for single users or small teams.

Step-by-step commands to get you running quickly:

# 1. Clone the project
git clone <your-repo-url>
cd scribe_mcp

# 2. Set up Python environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 3. Install the MCP server in editable mode with development extras
python -m pip install -e ".[dev]"

# 4. Optional: verify installation path
python -m pip install .

Additional configuration and usage notes

Configure the server for local or enterprise deployments. SQLite provides zero-config storage and is ideal for individuals or small teams. PostgreSQL offers more robust scaling for larger teams or production environments. When using PostgreSQL, you can bootstrap interactively using a single command, and the bootstrap process will write the necessary environment variables into your runtime configuration.

Connection and client setup examples

To connect clients like Claude Code or Codex MCP, you register the MCP with the client and point the client to run the server from the installed path. You can run the MCP server locally and point the client to connect over an HTTP-based MCP endpoint exposed by the server.

Security and reliability notes

The server provides write-ahead logging, atomic file operations, and integrity verification to ensure safe, crash-resistant behavior. Access control and input sanitization prevent unsafe path traversal and unauthorized edits. An audit trail records all changes and tool invocations for compliance and traceability.

Troubleshooting and quick checks

If the server fails to start or logs indicate a misconfiguration, verify dependencies, correct environment variable values, and ensure the runtime command points to the server executable. Use the quick smoke test to validate the MCP server is responding and healthy.

Examples of common workflows

- Create a new architecture template for a project and initialize its registry entry. - Append a milestone log entry after a sprint review and auto-promote the project from planning to in_progress when appropriate. - Run a structured diff on a document to apply patches with explicit change ranges and keep an audit trail.

Available tools

set_project

append_entry

Log progress entries, update activity metrics, and optionally promote project state.

manage_docs

Apply atomic updates to architecture, phase plans, checklists, and research docs with a documented history.

read_file

Read and analyze code or markdown files for signatures, structure, and exact line ranges with code intelligence capabilities.

scribe_doctor

Run readiness checks to verify repo root configuration, vector index status, and environment setup.

read_recent

Query recently logged entries for a project.

list_projects

List registered projects with filters and metadata.