@horatius/mcp

Model Context Protocol (MCP) server for Horatius knowledge management platform. Enables AI assistants like Claude to access and manage your solutions.

Installation

No installation needed! The MCP server runs via npx.

Quick Start (MCP Only)

Perfect if you only want to use Horatius with Claude and don't need the CLI tool.

Step 1: Get an API Key

Visit horatius.app/settings and generate an API key.

Step 2: Add to Claude Desktop Config

Claude Desktop (~/.config/claude/claude_desktop_config.json on macOS/Linux or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "horatius": {
      "command": "npx",
      "args": ["-y", "@horatius/mcp"],
      "env": {
        "HORATIUS_API_KEY": "hrt_your_api_key_here"
      }
    }
  }
}

Claude Code:

claude mcp add --transport stdio horatius --env HORATIUS_API_KEY=hrt_your_api_key_here -- npx -y @horatius/mcp

Step 3: Restart Claude Desktop

That's it! ✅

Setup with Shared Configuration

Best if you're using multiple Horatius tools (CLI + MCP + GUI).

Step 1: Get an API Key

Visit horatius.app/settings and generate an API key.

Step 2: Configure using the CLI

npm install -g @horatius/cli
hrt config set apiKey "hrt_your_api_key_here"

Step 3: Add MCP Server (No API Key Needed!)

Claude Desktop:

{
  "mcpServers": {
    "horatius": {
      "command": "npx",
      "args": ["-y", "@horatius/mcp"]
    }
  }
}

Claude Code:

claude mcp add --transport stdio horatius -- npx -y @horatius/mcp

Step 4: Restart Claude Desktop

The MCP server automatically uses your CLI configuration. No environment variables needed! 🎉

Local Development/Testing

If you're running a local Horatius server, set the HORATIUS_API_URL to your local instance:

Using Environment Variable:

{
  "mcpServers": {
    "horatius": {
      "command": "npx",
      "args": ["-y", "@horatius/mcp"],
      "env": {
        "HORATIUS_API_KEY": "hrt_your_api_key_here",
        "HORATIUS_API_URL": "http://localhost:3000"
      }
    }
  }
}

Using CLI Config:

hrt config set apiKey "hrt_your_api_key_here"
hrt config set apiUrl "http://localhost:3000"

Then restart Claude Desktop.

Available Tools

The MCP server exposes these tools to AI assistants:

CRUD Operations

• list_solutions - List all solutions (with filtering and search)
• get_solution - Get detailed solution by ID
• add_solution - Create a new solution
• update_solution - Update an existing solution
• delete_solution - Delete a solution by ID

Discovery & Analytics

• list_tags - Get all tags with usage counts
• get_stats - Get knowledge base statistics
• get_related_solutions - Find related solutions by shared tags

Usage Example

In Claude Desktop, you can ask:

"Show me all solutions tagged with 'docker'"

"Add a new solution about fixing PostgreSQL connection issues"

"Find solutions related to solution #42"

Configuration

The MCP server uses shared configuration with the Horatius CLI.

Configuration Priority:

1. Environment variables (highest priority - set in MCP config)
2. CLI config file (~/.horatius/config.json)
3. Defaults

Environment Variables

• HORATIUS_API_KEY (optional): Your API key - only needed if not using CLI config
• HORATIUS_API_URL (optional): API base URL (default: https://horatius.app)

Shared Configuration

When you set your API key with hrt config set apiKey, it's automatically available to:

• ✅ Horatius CLI (hrt command)
• ✅ Horatius MCP Server (this package)
• ✅ Horatius GUI (desktop application)

This means you only need to configure your API key once, and all tools work seamlessly!

Troubleshooting

"MISSING_KEY: No API key found" Error

The MCP server couldn't find your API key. You have two options:

Option 1 (Recommended): Configure using the CLI:

npm install -g @horatius/cli
hrt config set apiKey "hrt_your_api_key_here"

Option 2: Add environment variable to your MCP config:

{
  "mcpServers": {
    "horatius": {
      "command": "npx",
      "args": ["-y", "@horatius/mcp"],
      "env": {
        "HORATIUS_API_KEY": "hrt_your_api_key_here"
      }
    }
  }
}

"INVALID_FORMAT" Error

Your API key must start with hrt_. Check for typos or extra spaces in your configuration.

"INVALID API KEY" Error

Your API key may be invalid or revoked. Generate a new one at horatius.app/settings.

Connection Issues

If using a local server, set HORATIUS_API_URL in your MCP config:

{
  "mcpServers": {
    "horatius": {
      "command": "npx",
      "args": ["-y", "@horatius/mcp"],
      "env": {
        "HORATIUS_API_URL": "https://horatius.app"
      }
    }
  }
}

Or via CLI:

hrt config set apiUrl "https://horatius.app"

Development

# Install dependencies
npm install

# Test locally
node bin/mcp-server.mjs

License

MIT