How do I install Oorep?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Oorep need an API key?

No required environment variable is listed on this record.

When was Oorep last checked?

Last checked 2026-11-10. MCP server and TypeScript SDK for OOREP homeopathic repertory and materia medica reference data.

Oorep MCP server

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 22.12 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:

Call search_repertory with symptom "headache worse night"
Return matching rubrics with remedies and their weights
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:

Use the search_repertory tool
Search for "headache worse night" in the default repertory
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:

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

Comparing Remedies

You: "Compare Aconite and Belladonna for fever symptoms"

Claude will:

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

Case Repertorization

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

Claude will:

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

Browsing Available Resources

You: "What repertories are available in OOREP?"

Claude will:

Use the list_available_repertories tool
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-correction

Resources

URI	Description	Content Type
`oorep://remedies/list`	Complete list of all 600+ remedies	JSON
`oorep://repertories/list`	All available repertories with metadata	JSON
`oorep://materia-medicas/list`	All available materia medicas	JSON
`oorep://help/search-syntax`	Search syntax guide with examples	Text

Prompts

`analyze-symptoms`

Guided workflow for systematic symptom analysis.

Arguments:

Name	Type	Required	Description
`symptom_description`	string	No	Initial symptom description

Workflow: Guides through symptom gathering → modality analysis → repertory search → synthesis

`remedy-comparison`

Compare multiple remedies side-by-side.

Arguments:

Name	Type	Required	Description
`remedies`	string	Yes	Comma-separated remedy names (2-6 remedies)

Example: remedies: "Aconite, Belladonna, Gelsemium"

`repertorization-workflow`

Step-by-step case taking and repertorization.

Workflow: 7-step process from symptom collection through remedy differentiation.

Search Syntax

Basic Search

headache                    # Simple term
headache night              # Multiple terms (AND)

Wildcards

head*                       # Matches: head, headache, heading
*ache                       # Matches: headache, stomachache

Exact Phrases

"worse at night"            # Exact phrase match
"throbbing pain"            # Must appear together

Exclusions

headache -migraine          # Headache but not migraine
fever -intermittent         # Fever excluding intermittent

Combined

head* pain -chronic "worse motion"

Tips

Minimum 3 characters per term
Wildcards only at word boundaries
Use repertory-specific terminology for better results

SDK Integration

For programmatic use with AI frameworks, see the SDK Integration Guide.

Supported frameworks: OpenAI, Vercel AI SDK, LangChain/LangGraph, Google Gemini

Quick example:

import { createOOREPClient } from 'oorep-mcp';

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

Configuration

All configuration via environment variables:

Variable	Default	Description
`OOREP_MCP_BASE_URL`	`https://www.oorep.com`	OOREP API base URL
`OOREP_MCP_TIMEOUT_MS`	`30000`	Request timeout (ms)
`OOREP_MCP_CACHE_TTL_MS`	`300000`	Cache TTL (ms), 0 to disable
`OOREP_MCP_MAX_RESULTS`	`100`	Maximum results cap
`OOREP_MCP_LOG_LEVEL`	`info`	`debug` \| `info` \| `warn` \| `error`
`OOREP_MCP_DEFAULT_REPERTORY`	`publicum`	Default repertory
`OOREP_MCP_DEFAULT_MATERIA_MEDICA`	`boericke`	Default materia medica
`OOREP_MCP_REMOTE_USER`	(unset)	If set, sends `X-Remote-User` header (numeric member ID) on all upstream requests

The MCP server maintains an anonymous OOREP session automatically. It performs a lightweight bootstrap request to fetch the required cookies and reuses them for subsequent search calls, so no additional authentication setup is necessary for public data.

Example with custom config:

{
  "mcpServers": {
    "oorep": {
      "command": "npx",
      "args": ["-y", "oorep-mcp"],
      "env": {
        "OOREP_MCP_TIMEOUT_MS": "60000",
        "OOREP_MCP_CACHE_TTL_MS": "600000",
        "OOREP_MCP_LOG_LEVEL": "debug"
      }
    }
  }
}

Architecture

graph TB
    subgraph Client[MCP Client]
        MCPClient((Claude, Codex,<br/>Gemini, etc.))
    end

    subgraph Server[OOREP MCP Server]
        Tools[Tools]
        Resources[Resources]
        Prompts[Prompts]
        SDK[SDK]

        subgraph SDKClient[OOREPClient]
            Cache[(Cache)]
            Dedup[Deduplicator]
            Validators[Validators]
        end

        subgraph HTTPClient[OOREPClient - HTTP]
            Session[Session mgmt]
            Retry[Retry logic]
            Timeout[Timeout handling]
        end

        Tools --> SDKClient
        Resources --> SDKClient
        Prompts --> SDKClient
        SDK --> SDKClient
        SDKClient --> HTTPClient
    end

    subgraph External[OOREP API]
        API[https://www.oorep.com]
    end

    MCPClient -->|MCP Protocol| Server
    HTTPClient -->|HTTPS| API

Key Components:

Cache: In-memory LRU cache with configurable TTL (default 5 min)
Deduplicator: Prevents duplicate concurrent requests for same data
Validators: Zod schemas validate all inputs before API calls
Session Management: Automatic cookie handling for OOREP API

Security Considerations

Input Validation

All inputs are validated using Zod schemas:

Symptom searches: 3-200 characters, trimmed of whitespace
Remedy names: 1-100 characters
Server-side sanitization: The OOREP API handles additional input sanitization

Error Handling

All errors are sanitized before being returned to clients
Internal details (stack traces, file paths) are never exposed
Network errors return generic messages

Data Privacy

No user credentials are stored or required
OOREP sessions are anonymous and cookie-based
No data is persisted to disk (memory cache only)
All inputs validated using Zod schemas
Errors are sanitized before returning to clients

Rate Limiting

The OOREP MCP Server does not implement internal rate limiting. However:

OOREP API Limits

The upstream OOREP API may have rate limits. If you exceed them, you'll receive a RateLimitError:

{
  content: [{ type: 'text', text: 'Error: Rate limit exceeded. Please try again later.' }],
  isError: true
}

Mitigation Strategies

Enable caching (default: 5 minutes TTL)

"env": { "OOREP_MCP_CACHE_TTL_MS": "300000" }

Reduce concurrent requests by using specific search terms

Increase cache TTL for frequently accessed data

"env": { "OOREP_MCP_CACHE_TTL_MS": "600000" }

Request Deduplication

The SDK client automatically deduplicates concurrent identical requests, reducing API load.

TypeScript Type Imports

Import types directly from the package for type-safe development:

import type {
  // Tool argument types
  SearchRepertoryArgs,
  SearchMateriaMedicaArgs,
  GetRemedyInfoArgs,
  ListRepertoriesArgs,
  ListMateriaMedicasArgs,

  // Result types
  RepertorySearchResult,
  MateriaMedicaSearchResult,
  RemedyInfo,
  RepertoryMetadata,
  MateriaMedicaMetadata,

  // Supporting types
  Rubric,
  Remedy,
  MateriaMedicaResult,
  MateriaMedicaSection,
  // SDK Client types
  OOREPClient,
  OOREPSDKConfig,
} from 'oorep-mcp';

Schema Validation

You can also import Zod schemas for runtime validation:

import {
  SearchRepertoryArgsSchema,
  RepertorySearchResultSchema,
  RemedyInfoSchema,
} from 'oorep-mcp';

// Validate external data
const validated = SearchRepertoryArgsSchema.parse(untrustedInput);

Troubleshooting

Server Not Appearing in Claude Desktop

Problem: The MCP indicator doesn't show up after configuration.

Solutions:

Completely quit Claude Desktop (Cmd+Q on macOS, not just close window)
Restart Claude Desktop and wait 10-15 seconds for MCP initialization
Check the configuration file for valid JSON syntax (use a JSON validator)
Check the logs:
- macOS: ~/Library/Logs/Claude/mcp*.log
- Windows: %APPDATA%\Claude\Logs\mcp*.log
Verify npx works: Run npx -y oorep-mcp in terminal to check if it starts

Connection Timeout Errors

Problem: "Connection timeout" or "Request timed out" errors.

Solutions:

Increase timeout in configuration:

"env": {
  "OOREP_MCP_TIMEOUT_MS": "60000"
}

Check network connectivity to https://www.oorep.com:
```
curl https://www.oorep.com
```
Check for firewall/proxy issues that might block connections

No Results Returned

Problem: Searches return empty results or "No results found".

Solutions:

Try broader search terms (e.g., "headache" instead of "headache left temple worse 3pm")
Remove filters like minWeight or specific repertory restrictions
Check if OOREP website is accessible at https://www.oorep.com
Try a different repertory: Ask Claude: "Search in the Kent repertory instead"

High Memory Usage

Problem: MCP server consuming excessive memory.

Solutions:

Reduce cache TTL to clear cache more frequently:

"env": {
  "OOREP_MCP_CACHE_TTL_MS": "60000"
}

Reduce max results:

"env": {
  "OOREP_MCP_MAX_RESULTS": "50"
}

Restart Claude Desktop periodically to clear cache

Permission Errors on macOS/Linux

Problem: "Permission denied" when running the server.

Solutions:

For global install: Ensure proper npm permissions
```
sudo npm install -g oorep-mcp
```
For npx (recommended): No permissions needed, use -y flag:
```
npx -y oorep-mcp
```

Viewing Detailed Logs

To see detailed debug logs for troubleshooting:

Set log level to debug:

"env": {
  "OOREP_MCP_LOG_LEVEL": "debug"
}

Check MCP logs:
- macOS: tail -f ~/Library/Logs/Claude/mcp*.log
- Windows: Check %APPDATA%\Claude\Logs\
Look for specific error patterns:
- NetworkError - Connection issues
- TimeoutError - Request taking too long
- ValidationError - Invalid input
- RateLimitError - Too many requests

Still Having Issues?

Check existing issues: https://github.com/Dhi13man/oorep-mcp/issues
Report a new issue: Include:
- Your OS and version
- Node.js version (node --version)
- Claude Desktop version
- Configuration (remove any sensitive data)
- Error logs from MCP log files
Join the discussion: Share your experience and get community help

Development

Prerequisites

Node.js ≥ 22.12.0
npm ≥ 10.0.0

Setup

git clone https://github.com/Dhi13man/oorep-mcp.git
cd oorep-mcp
npm ci

Commands

npm run build          # Compile TypeScript
npm run typecheck      # Type checking only
npm run dev            # Development mode with watch
npm test               # Run all tests
npm run test:watch     # Watch mode
npm run test:coverage  # Coverage report
npm run test:e2e       # Live OOREP integration (requires network access)
npm run lint           # ESLint
npm run format         # Prettier

Test Structure

src/
├── **/*.unit.test.ts        # Unit tests (mocked dependencies)
└── **/*.integration.test.ts # Integration tests (real implementations)

1100+ tests with 95%+ coverage
Unit tests use mocked dependencies
Integration tests use real implementations with mocked HTTP

Disclaimer

This tool is for educational and informational purposes only.

Not medical advice - Not a substitute for professional medical consultation
Consult practitioners - Always consult qualified homeopathic practitioners
Not for diagnosis - Not intended for diagnosing or treating medical conditions

Homeopathic treatment should only be undertaken under the guidance of qualified professionals.

License

MIT License - see LICENSE file for details.

Acknowledgments

OOREP Team: For creating and maintaining the open-source OOREP platform
Anthropic: For the Model Context Protocol and Claude
MCP Community: For tools, documentation, and support

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Oorep?

Does Oorep need an API key?

What transport does Oorep use?

When was Oorep last checked?

Documentation

OOREP MCP Server

TL;DR

What is OOREP?

How Homeopathic Data is Structured

Features

Quick Start

1. Add to Claude Desktop

2. Restart Claude Desktop

3. Start Using

Installation

NPX (Recommended)

npm Global

npm Local (for SDK usage)

Platform Configuration

Claude Code

Option A: CLI

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

Claude Desktop

Codex CLI

Gemini CLI

Usage Examples

Searching for Remedies

Getting Detailed Remedy Information

Comparing Remedies

Case Repertorization

Browsing Available Resources

API Reference

Tools

search_repertory

search_materia_medica

get_remedy_info

list_available_repertories

list_available_materia_medicas

Structured Response Format

Resources

Prompts

analyze-symptoms

remedy-comparison

repertorization-workflow

Search Syntax

Basic Search

Wildcards

Exact Phrases

Exclusions

Combined

Tips

SDK Integration

Configuration

Architecture

Security Considerations

Input Validation

Error Handling

Data Privacy

Rate Limiting

OOREP API Limits

Mitigation Strategies

Request Deduplication

TypeScript Type Imports

Schema Validation

Troubleshooting

Server Not Appearing in Claude Desktop

Connection Timeout Errors

No Results Returned

High Memory Usage

Permission Errors on macOS/Linux

Viewing Detailed Logs

Still Having Issues?

Development

Prerequisites

Setup

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

`search_repertory`

`search_materia_medica`

`get_remedy_info`

`list_available_repertories`

`list_available_materia_medicas`

`analyze-symptoms`

`remedy-comparison`

`repertorization-workflow`