io.github.Dhi13man/oorep-mcp

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:

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

1. Enable caching (default: 5 minutes TTL)

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

2. Reduce concurrent requests by using specific search terms

3. 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:

1. Completely quit Claude Desktop (Cmd+Q on macOS, not just close window)
2. Restart Claude Desktop and wait 10-15 seconds for MCP initialization
3. Check the configuration file for valid JSON syntax (use a JSON validator)
4. Check the logs:
   • macOS: ~/Library/Logs/Claude/mcp*.log
   • Windows: %APPDATA%\Claude\Logs\mcp*.log
5. 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:

1. Increase timeout in configuration:

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

2. Check network connectivity to https://www.oorep.com:

   curl https://www.oorep.com
   

3. Check for firewall/proxy issues that might block connections

No Results Returned

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

Solutions:

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

High Memory Usage

Problem: MCP server consuming excessive memory.

Solutions:

1. Reduce cache TTL to clear cache more frequently:

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

2. Reduce max results:

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

3. Restart Claude Desktop periodically to clear cache

Permission Errors on macOS/Linux

Problem: "Permission denied" when running the server.

Solutions:

1. For global install: Ensure proper npm permissions

   sudo npm install -g oorep-mcp
   

2. For npx (recommended): No permissions needed, use -y flag:

   npx -y oorep-mcp
   

Viewing Detailed Logs

To see detailed debug logs for troubleshooting:

1. Set log level to debug:

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

2. Check MCP logs:

   • macOS: tail -f ~/Library/Logs/Claude/mcp*.log
   • Windows: Check %APPDATA%\Claude\Logs\

3. Look for specific error patterns:

   • NetworkError - Connection issues
   • TimeoutError - Request taking too long
   • ValidationError - Invalid input
   • RateLimitError - Too many requests

Still Having Issues?

1. Check existing issues: https://github.com/Dhi13man/oorep-mcp/issues
2. 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
3. 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

Links

• OOREP Website: https://www.oorep.com
• OOREP GitHub: https://github.com/nondeterministic/oorep
• MCP Documentation: https://modelcontextprotocol.io
• Issue Tracker: https://github.com/Dhi13man/oorep-mcp/issues
• npm Package: https://www.npmjs.com/package/oorep-mcp
• Support Development: https://www.buymeacoffee.com/dhi13man