home / mcp / homello mcp server

Homello MCP Server

Connect your LLM to Homello’s real-estate agents via Model Context Protocol (MCP).

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "homello-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@homello/mcp"
      ],
      "env": {
        "HOMELLO_DEBUG": "0",
        "HOMELLO_API_KEY": "YOUR_API_KEY",
        "HOMELLO_API_BASE": "https://api.homello.ai",
        "HOMELLO_TIMEOUT_SECS": "30",
        "HOMELLO_DEFAULT_MARKET": "US"
      }
    }
  }
}

You run a lightweight Standalone MCP server that exposes the Homello tool over stdio. It enables clients to query Homello metadata and effective runtime configuration through the homello.get_info tool, making it easy to discover how the Homello platform is configured for your environment.

How to use

You start the MCP server locally and connect to it with an MCP client. The server communicates over stdio, so the client exchanges requests and responses through the standard input and output streams. The primary tool you’ll use is homello.get_info, which returns platform metadata, including the API base, market, timeout, and debug settings. Your client can rely on this to adapt prompts, dashboards, or API calls to your current runtime configuration.

How to install

Prerequisites: You need Node.js (version 20 or newer) installed on your system. You also need a tool capable of running MCP from the command line, such as npm or npx.

# Run once without installation
npx -y @homello/mcp

# Or add to a project and run from there
npm i -D @homello/mcp
npx mcp

Configuration and runtime

Set key environment variables to configure the MCP server and your Homello integration. These values can come from your environment, your Goose extension configuration, or local development toggles.

{
  "envVars": [
    {"name": "HOMELLO_API_BASE", "description": "Base URL for Homello API", "example": "https://api.homello.ai"},
    {"name": "HOMELLO_API_KEY", "description": "API key for authentication", "example": "YOUR_API_KEY"},
    {"name": "HOMELLO_DEFAULT_MARKET", "description": "Default market code", "example": "US"},
    {"name": "HOMELLO_TIMEOUT_SECS", "description": "Request timeout in seconds", "example": "30"},
    {"name": "HOMELLO_DEBUG", "description": "Enable debug logging", "example": "0"}
  ]
}

Using the stdio MCP server

The server runs as a stdio process. You start it with a command that loads the MCP package and enters the default start flow. The canonical startup command is shown here as the standard way to launch the server.

npx -y @homello/mcp

Goose extension integration (auto-install an extension)

If you use Goose to manage extensions, you can install an entry that enables the Homello MCP tool to be discovered and used automatically by the host.

# Install/update the extension entry
npx -y @homello/mcp install \
  --enabled=true \
  --timeout=300 \
  --available-tools homello.get_info \
  --env HOMELLO_API_BASE=https://api.homello.ai \
  --env-key HOMELLO_API_KEY

# Remove the extension entry
npx -y @homello/mcp uninstall

CLI usage

You can start and manage the MCP server from the command line using the MCP CLI. The key commands are shown below.

# Start the stdio server (default action)
mcp start

# Create or update Goose extension entry
mcp install [options]

# Remove Goose extension entry
mcp uninstall [--id homello]

Available tools

homello.get_info

Returns Homello product/docs metadata plus effective runtime config (API base, market, timeout, debug). The response includes a structuredContent payload for structured content consumption.