Jacky — Your autonomous desktop companion

Jacky can act as a Model Context Protocol (MCP) server, exposing its tools to external AI agents such as Claude Desktop, Windsurf, or any MCP-compatible client. This allows other agents to make Jacky speak aloud, show notifications, change emotions, run routines, set timers, switch skins, and even pipe queries through Jacky's full LLM agent pipeline.

The server uses the SSE (Server-Sent Events) transport and is bound to 127.0.0.1 (localhost only) for security.

Available Tools

Tool	Description
`jacky_say`	Speak text aloud with voice and show a speech bubble
`jacky_notify`	Show a system tray notification (no voice)
`jacky_emote`	Change Jacky's animation/emotion state
`jacky_react_to`	Have Jacky react to text with an LLM-generated response
`jacky_ask`	Send text through Jacky's full agent pipeline (routines, tools, LLM)
`jacky_run_routine`	Run a Jacky routine by ID with optional variables
`jacky_set_timer`	Create a countdown timer
`jacky_set_alarm`	Create an alarm clock
`jacky_status`	Get Jacky's current status (version, pet state, LLM/TTS availability)
`jacky_skin`	Switch Jacky to an already-installed skin by name
`jacky_move_to`	Walk Jacky to absolute screen coordinates (pixels)
`jacky_move`	Walk Jacky a relative distance in pixels (left/right/up/down/top/bottom)

Configuration

Step 1: Enable the Permission

Right-click Jacky → Settings.
Go to the Permissions tab.
Find Expose MCP server (allow_mcp_server) and check the box.
Click Save.

Step 2: Enable the Server

Open Settings → Integrations tab.
Switch to the MCP Server subtab.
Check Enable MCP server (SSE transport).
Configure the Port (default: 9877).
Select which Allowed actions external agents can execute.
(Optional) Set an Access token — if set, clients must send Authorization: Bearer <token>. Click Regenerate to create a new token.
Click Save.

Warning

Security: The server binds to 127.0.0.1 only — it is not accessible from other machines on your network. The access token is optional but recommended. If set, clients must include it in the Authorization header or ?token= query parameter.

Connecting External Agents

Claude Desktop

Add Jacky to your Claude Desktop MCP configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "jacky": {
      "url": "http://127.0.0.1:9877/sse",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Windsurf

Add Jacky to your Windsurf MCP config (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "jacky": {
      "url": "http://127.0.0.1:9877/sse",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Other MCP Clients

Any MCP client that supports the SSE transport can connect to:

http://127.0.0.1:9877/sse

If you set a token, include it as a Bearer token in the Authorization header.

Note

If you did not set a token, omit the headers field entirely.

Usage Examples

Once connected, the AI agent can call Jacky's tools naturally:

"Tell the user the build finished" → agent calls jacky_say(text="Your build finished successfully!")
"Set a 5-minute timer for tea" → agent calls jacky_set_timer(seconds=300, label="Tea is ready")
"Make Jacky look happy" → agent calls jacky_emote(state="happy")
"Ask Jacky about the weather" → agent calls jacky_ask(text="What's the weather like?")
"Switch Jacky to the Forest Ranger skin" → agent calls jacky_skin(name="Forest Ranger 3")
"Check Jacky's current state" → agent calls jacky_status()
"Send Jacky to the top-right corner" → agent calls jacky_move_to(x=1700, y=100)
"Move Jacky 100 pixels to the left" → agent calls jacky_move(direction="left", distance=100)

MCP Server