OrgBrain

You deploy OrgBrain MCP Server to extract knowledge from many repositories in your organization and query cross-repo data, such as type definitions, user flows, dependencies, and infrastructure maps. It centralizes extraction, versioning, and visualization so you can compare across repos and track changes over time.

How to use

You connect to the server from an MCP client that communicates over stdio. Start the server locally, then configure your client to spawn it as a subprocess. You can run in development mode to watch changes live or build and run compiled output for production-like behavior.

How to install

# Install dependencies using your preferred package manager
pnpm install

# Bootstrap config from a GitHub org (requires authentication via GitHub CLI)
pnpm add:org-repos <your-org>

# Or copy and customize the example config
cp config/example.repos.yaml config/repos.yaml

# Run in development mode (watches for changes)
pnpm dev

# Or build then run compiled output
pnpm build
pnpm start

The server reads MCP_CONFIG (defaults to config/repos.yaml). You can override the path like this:

MCP_CONFIG=path/to/custom.yaml pnpm dev

Configuration

The server uses a YAML configuration that defines global settings, repository-specific details, and which extractors to run. The configuration structure includes global settings for cache and knowledge storage, and per-repo sections that specify repository URL, language, type, tracking branches, and selected extractors.

# Global settings example
version: "1.0"
cache_dir: .repo-cache
knowledge_dir: knowledge/extracted

# Optional: customize diagram colors by repo type
diagram_styles:
  frontend: "#4CAF50"
  backend:  "#FF9800"
  infrastructure: "#607D8B"

repositories:
  my-repo:
    url: https://github.com/org/repo.git
    description: "What this repo does"
    type: frontend
    language: typescript
    default_branch: main
    track:
      branches: [main, develop]
    extractors:
      - name: type_definitions
        config: { prioritize: ["src/models/", "src/types/"] }
      - name: data_flow
      - name: journey_impact

Environment variables

Set environment variables to control how the MCP server runs and which config it loads. The following variable is used to specify the path to the configuration file.

MCP_CONFIG=config/repos.yaml

Using from an MCP client

You connect from an MCP client by spawning the server as a subprocess and configuring the client to talk to it. Two common scenarios are shown here.

# Cursor (local project integration)
{
  "mcpServers": {
    "orgbrain": {
      "command": "node",
      "args": ["/absolute/path/to/orgbrain-mcp-server/dist/index.js"],
      "env": {
        "MCP_CONFIG": "/absolute/path/to/orgbrain-mcp-server/config/repos.yaml"
      }
    }
  }
}

# Claude Desktop
{
  "mcpServers": {
    "orgbrain": {
      "command": "node",
      "args": ["/absolute/path/to/orgbrain-mcp-server/dist/index.js"],
      "env": {
        "MCP_CONFIG": "/absolute/path/to/orgbrain-mcp-server/config/repos.yaml"
      }
    }
  }
}

CLI usage

You can trigger knowledge extraction and interact with the MCP server using the MCP CLI, which delegates to the running server.

# Example CLI usage preparing a call to a running server
npx @modelcontextprotocol/cli@latest call \
  --command list_repos \
  --server "node dist/index.js"

Security and best practices

Keep your config.yaml and knowledge data secure. Limit access to the MCP server endpoints, rotate credentials for any external connections, and prune stale data for repos that are disabled. Regularly review extractor configurations to avoid unnecessary processing and long-running operations.

Examples and resources

This server supports a variety of extractors to collect type definitions, user flows, data dependencies, and infrastructure mappings. You can tailor extractor configurations per repository to optimize performance and coverage.

Available tools

list_repos

List repositories with their latest extracted ref to understand current scope and recent activity across the organization.

list_refs

Show branches and tags for each repository to know which refs are available and their order by date.

query_nips

Aggregate NIP usage across repositories to understand cross-repo protocol usage.

query_flows

Aggregate user flows and screens to map common journeys across services.

query_monorepos

Aggregate monorepo structures to understand workspace layouts.

query_data_flow

Aggregate service dependencies to map data flow between components.

query_infra

Aggregate Kubernetes and Terraform resources to get an infrastructure overview.

query_types

Search type definitions across repositories by name, kind, or repo.

query_shared_types

Identify types that appear in multiple repositories to find shared data contracts.

query_type_relationships

Get type relationships within a repository (extends, contains, implements).

generate_type_flow_diagram

Generate Mermaid diagrams showing cross-repo type flows.

generate_diagram

Create Mermaid diagrams for a repository or ecosystem to visualize structures.

generate_c4_diagram

Generate C4-style architecture diagrams with optional detailed view and export.

extract_ref

Extract a specific ref for a repository to refresh its knowledge.

extract_all

Extract all enabled repositories according to their configured refs.

compare_versions

List available refs for comparison across repositories.

diff_versions

Compare extractors and data between two refs to surface changes.

connect_org

Add repositories from a GitHub organization to the MCP config.

disconnect_repo

Remove a repository from the MCP configuration.

toggle_repo

Enable or disable a repository in the MCP configuration.

job_status

Check the status of ongoing extraction jobs.