OOREP MCP Server

An MCP server and TypeScript client SDK that gives AI assistants access to OOREP's homeopathic repertory and materia medica reference data.

TL;DR

# Install and run (no setup required)
npx -y oorep-mcp

// Or use programmatically
import { createOOREPClient } from 'oorep-mcp';

const client = createOOREPClient();
const results = await client.searchRepertory({ symptom: 'headache worse motion' });
console.log(results.rubrics);
client.destroy();

Ask your AI assistant: "Search OOREP for remedies for throbbing headache worse from light"

What is OOREP?

OOREP (Open Online Repertory) is an open-source homeopathic database containing:

• 12+ Repertories - Systematic indexes of symptoms mapped to remedies (Kent, Boger, Boericke, etc.)
• Multiple Materia Medicas - Detailed remedy descriptions and therapeutic indications
• 600+ Remedies - Comprehensive remedy database with names, abbreviations, and alternates

How Homeopathic Data is Structured

graph TB
    subgraph Repertory[Repertory Structure]
        Chapter[Chapter<br/>e.g. Head]
        Rubric[Rubric<br/>e.g. Pain - Throbbing]
        R1[Belladonna - 4]
        R2[Glonoine - 3]
        R3[Natrum mur - 2]
        Chapter --> Rubric
        Rubric --> R1
        Rubric --> R2
        Rubric --> R3
    end

    subgraph MateriaMedica[Materia Medica Structure]
        Remedy[Remedy<br/>e.g. Belladonna]
        S1[Mind: Sudden onset...]
        S2[Head: Throbbing pain...]
        S3[...]
        Remedy --> S1
        Remedy --> S2
        Remedy --> S3
    end

This MCP server enables AI assistants to query this data programmatically.

Features

| Feature | Description | |---------|-------------| | Search Repertories | Query symptoms across 12+ repertories, get matching rubrics with weighted remedies | | Search Materia Medicas | Find remedy descriptions and indications from multiple sources | | Remedy Information | Get comprehensive details for 600+ remedies | | List Resources | Browse available repertories, materia medicas, and remedies | | Guided Workflows | Prompts for symptom analysis, remedy comparison, case repertorization | | Structured Responses | MCP 2025-06-18 compliant with outputSchema and structuredContent | | Performance | Built-in caching (5min TTL), request deduplication, automatic retries | | Type Safety | Full TypeScript with Zod validation on all inputs | | Security | Input sanitization, error message sanitization, no credentials required | | SDK Adapters | Direct integration with OpenAI, Vercel AI SDK, LangChain, Google Gemini |

Quick Start

Requires Node.js 20 or newer with npm/npx.

1. Add to Claude Desktop

macOS: Edit ~/Library/Application Support/Claude/claude_desktop_config.json Windows: Edit %APPDATA%\Claude\claude_desktop_config.json

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

2. Restart Claude Desktop

Quit completely (Cmd+Q / Alt+F4), then reopen.

3. Start Using

You: "Search OOREP for remedies for headache worse at night"

Claude will:

1. Call search_repertory with symptom "headache worse night"
2. Return matching rubrics with remedies and their weights
3. Explain the results in context

Installation

NPX (Recommended)

No installation required:

npx -y oorep-mcp

npm Global

npm install -g oorep-mcp
oorep-mcp

npm Local (for SDK usage)

npm install oorep-mcp

Platform Configuration

Claude Code

Option A: CLI

claude mcp add oorep -- npx -y oorep-mcp

Option B: Config file (~/.claude.json)

{
  "mcpServers": {
    "oorep": {
      "command": "npx",
      "args": ["-y", "oorep-mcp"],
      "env": {
        "OOREP_MCP_BASE_URL": "https://www.oorep.com",
        "OOREP_MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Verify: Run /mcp in Claude Code

Claude Desktop

Config locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "oorep": {
      "command": "npx",
      "args": ["-y", "oorep-mcp"],
      "env": {
        "OOREP_MCP_BASE_URL": "https://www.oorep.com",
        "OOREP_MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Important: Quit completely (Cmd+Q), not just close window.

Codex CLI

Config: ~/.codex/config.toml (macOS/Linux) or C:\Users\<Username>\.codex\config.toml (Windows)

[mcp_servers.oorep]
command = "npx"
args = ["-y", "oorep-mcp"]
startup_timeout_sec = 15.0
tool_timeout_sec = 60.0

[mcp_servers.oorep.env]
OOREP_MCP_BASE_URL = "https://www.oorep.com"
OOREP_MCP_LOG_LEVEL = "info"

Or via CLI:

codex mcp add oorep --env OOREP_MCP_BASE_URL=https://www.oorep.com --env OOREP_MCP_LOG_LEVEL=info -- npx -y oorep-mcp

Verify: Run codex mcp list

Gemini CLI

Config: ~/.gemini/settings.json

{
  "mcpServers": {
    "oorep": {
      "command": "npx",
      "args": ["-y", "oorep-mcp"],
      "env": {
        "OOREP_MCP_BASE_URL": "https://www.oorep.com",
        "OOREP_MCP_LOG_LEVEL": "info"
      },
      "timeout": 30000
    }
  }
}

Usage Examples

Once installed, you can interact with OOREP through Claude naturally:

Searching for Remedies

You: "Can you search OOREP for remedies for headache that's worse at night?"

Claude will:

1. Use the search_repertory tool
2. Search for "headache worse night" in the default repertory
3. Return matching rubrics with remedy recommendations and their weights

Getting Detailed Remedy Information

You: "Tell me more about Aconite - what conditions is it used for?"

Claude will:

1. Use the get_remedy_info tool to fetch details about Aconite
2. Provide information about its common uses, characteristics, and therapeutic applications

Comparing Remedies

You: "Compare Aconite and Belladonna for fever symptoms"

Claude will:

1. Use the remedy-comparison prompt
2. Search materia medicas for both remedies
3. Provide a side-by-side comparison focusing on fever symptoms
4. Highlight key differentiating factors

Case Repertorization

You: "I want to repertorize a case with these symptoms: anxiety, palpitations, and insomnia"

Claude will:

1. Use the repertorization-workflow prompt
2. Guide you through systematic symptom analysis
3. Search relevant rubrics for each symptom
4. Help synthesize results to identify well-indicated remedies

Browsing Available Resources

You: "What repertories are available in OOREP?"

Claude will:

1. Use the list_available_repertories tool
2. Show all 12+ available repertories with their names and descriptions

API Reference

Tools

search_repertory

Search for symptoms in homeopathic repertories.

Parameters:

| Name | Type | Required | Default | Description | |------|------|----------|---------|-------------| | symptom | string | Yes | - | Symptom to search (3-200 chars). Supports wildcards. | | repertory | string | No | publicum | Repertory abbreviation (e.g., kent, boger) | | minWeight | number | No | 1 | Minimum remedy weight (1-4) | | maxResults | number | No | 20 | Maximum rubrics to return (1-100) | | includeRemedyStats | boolean | No | true | Include aggregated remedy statistics |

Returns:

{
  totalResults: number;
  rubrics: Array<{
    rubric: string;           // Full path: "Head > Pain > Throbbing"
    text: string | null;      // Additional rubric text
    repertory: string;        // Repertory abbreviation
    remedies: Array<{
      name: string;           // Full name: "Belladonna"
      abbreviation: string;   // "Bell."
      weight: number;         // 1-4
    }>;
  }>;
  remedyStats?: Array<{       // If includeRemedyStats=true
    name: string;
    abbreviation: string;
    count: number;            // Times appearing
    cumulativeWeight: number; // Sum of weights
  }>;
}

search_materia_medica

Search materia medica texts for remedy descriptions.

Parameters:

| Name | Type | Required | Default | Description | |------|------|----------|---------|-------------| | symptom | string | Yes | - | Symptom to search (3-200 chars) | | materiamedica | string | No | boericke | Materia medica abbreviation | | remedy | string | No | - | Filter to specific remedy | | maxResults | number | No | 10 | Maximum results (1-50) |

Returns:

{
  totalResults: number;
  results: Array<{
    remedy: string;           // "Aconitum napellus"
    materiaMedica: string;    // "boericke"
    sections: Array<{
      heading: string;        // "Mind", "Head", etc.
      content: string;        // Section text
      depth: number;          // Heading depth
    }>;
  }>;
}

get_remedy_info

Get detailed information about a specific remedy.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | remedy | string | Yes | Remedy name, abbreviation, or alternate name (1-100 chars) |

Returns:

{
  id: number;
  nameAbbrev: string;    // "Acon."
  nameLong: string;      // "Aconitum napellus"
  namealt: string[];     // ["Aconite", "Monkshood"]
} | null  // null if not found

Matching behavior:

• Exact match on abbreviation, long name, or alternate names (case-insensitive)
• Partial match for queries ≥3 characters

list_available_repertories

List all accessible repertories.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | language | string | No | Filter by language code (e.g., en, de) |

Returns:

Array<{
  abbreviation: string;  // "kent"
  title: string;         // "Kent Repertory"
  author: string;        // "James Tyler Kent"
  language: string;      // "en"
}>

list_available_materia_medicas

List all accessible materia medica texts.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | language | string | No | Filter by language code |

Returns:

Array<{
  abbreviation: string;  // "boericke"
  title: string;         // "Boericke Materia Medica"
  author: string;        // "William Boericke"
  language: string;      // "en"
}>

Structured Response Format

All tools support the MCP 2025-06-18 specification with structured responses:

Response Structure:

{
  // Text content for backwards compatibility
  content: [{
    type: 'text',
    text: '{"totalResults": 42, "rubrics": [...]}' // JSON string
  }],

  // Machine-parseable structured content
  structuredContent: {
    totalResults: 42,
    rubrics: [...]  // Actual JavaScript object
  }
}

Benefits:

• outputSchema: Each tool definition includes a JSON Schema defining the expected output structure
• structuredContent: Direct access to typed results without JSON parsing
• Backwards Compatible: Text content always included for older clients
• Error Handling: Errors return isError: true for LLM self-correct