Skip to main content
Glama
zhigang1992

Happy Server MCP

by zhigang1992
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

Happy Server MCP

MCP (Model Context Protocol) server for managing Happy AI sessions. This allows AI agents to interact with Happy sessions programmatically.

Features

  • List Sessions: Query all your Happy AI sessions with their titles, working directories, and activity status

  • List Machines: See all registered machines and their online/offline status

  • List Recent Paths: Get recently used working directories for a machine

  • Read Messages: Fetch recent messages from any session to see conversation history

  • Send Messages: Trigger a session to work by sending it a message

  • Start Sessions: Spawn new AI sessions on any connected machine

  • Archive Sessions: Stop and archive sessions when done

  • Wait for Idle: Wait for a session to finish processing

Installation

npm install -g @zhigang1992/happy-server-mcp

Prerequisites

You must be authenticated with Happy CLI. Run:

happy auth

This creates credentials at ~/.happy/access.key that the MCP server uses.

Usage with Claude

Add to your Claude configuration:

{ "mcpServers": { "happy": { "command": "happy-server-mcp" } } }

Or with npx:

{ "mcpServers": { "happy": { "command": "npx", "args": ["@zhigang1992/happy-server-mcp"] } } }

Available Tools

happy_list_sessions

List all Happy AI sessions. Returns session IDs, titles, paths, machines, and activity status.

Parameters:

Name

Type

Required

Default

Description

limit

number

No

50

Maximum number of sessions to return

Example:

Use happy_list_sessions to see all my active sessions

happy_list_machines

List all machines registered with Happy. Returns machine IDs, hostnames, platforms, and activity status.

Parameters: None

Example:

Use happy_list_machines to see which machines are online

happy_list_recent_paths

List recently used folder paths for a machine. Useful for starting sessions in familiar locations.

Parameters:

Name

Type

Required

Default

Description

machine_id

string

Yes

-

The machine ID to get recent paths for

limit

number

No

20

Maximum number of paths to return

Example:

Use happy_list_recent_paths with machine_id "abc123" to see recent working directories

happy_read_messages

Read recent messages from a Happy AI session. Use this to see the conversation history.

Parameters:

Name

Type

Required

Default

Description

session_id

string

Yes

-

The session ID to read messages from

limit

number

No

20

Maximum number of messages to return

Example:

Use happy_read_messages with session_id "xyz789" to see what the AI has been working on

happy_send_message

Send a message to a Happy AI session to trigger it to work. The message will be sent with bypass permissions mode.

Parameters:

Name

Type

Required

Default

Description

session_id

string

Yes

-

The session ID to send the message to

message

string

Yes

-

The message text to send

wait

boolean

No

false

If true, wait for AI to finish processing before returning

Example:

Use happy_send_message with session_id "xyz789" and message "Fix the bug in auth.ts" and wait=true

happy_start_session

Start a new Happy AI session on a machine. Use happy_list_machines to find available machines first.

Parameters:

Name

Type

Required

Default

Description

machine_id

string

Yes

-

The machine ID to start the session on

directory

string

Yes

-

The directory path to run the session in

message

string

No

-

Optional initial message to send to start the session working

agent

"claude" | "codex"

No

"claude"

Agent type to use

wait

boolean

No

false

If true, wait for AI to finish processing initial message before returning

Example:

Use happy_start_session with machine_id "abc123", directory "/home/user/project", message "Review the codebase and suggest improvements", and wait=true

happy_archive_session

Archive (stop) a Happy AI session. The session will be terminated and marked as inactive.

Parameters:

Name

Type

Required

Default

Description

session_id

string

Yes

-

The session ID to archive

Example:

Use happy_archive_session with session_id "xyz789" to stop the session

happy_wait_for_idle

Wait for a Happy AI session to become idle (finish processing). Useful after sending a message to wait for AI to complete its work.

Parameters:

Name

Type

Required

Default

Description

session_id

string

Yes

-

The session ID to wait for

timeout_seconds

number

No

120

Maximum time to wait in seconds

Example:

Use happy_wait_for_idle with session_id "xyz789" to wait for the AI to finish

Common Workflows

Start a session and wait for completion

  1. Use happy_list_machines to find an online machine

  2. Use happy_list_recent_paths to find a good working directory

  3. Use happy_start_session with wait=true to start and wait for the initial task

Monitor an existing session

  1. Use happy_list_sessions to find active sessions

  2. Use happy_read_messages to see what the AI is working on

  3. Use happy_send_message to give it new instructions

Clean up old sessions

  1. Use happy_list_sessions to see all sessions

  2. Use happy_archive_session to stop sessions you no longer need

Environment Variables

  • HAPPY_SERVER_URL: Override the Happy server URL (default: https://happy.engineering)

License

MIT

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/zhigang1992/happy-server-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server