skyspark-mcp

MCP server for SkySpark — connect AI assistants to your building automation data.

Evaluate Axon expressions, read/write records, manage functions, and explore your SkySpark projects through the Model Context Protocol.

Features

• 21 tools for comprehensive SkySpark interaction
• SCRAM, token, or no-auth — works with any network setup (including Tailscale)
• Multi-project — target different projects from the same server
• Base64-safe commits — avoids Axon ${} string interpolation issues
• Production-tested — used daily for building analytics dashboards

Quick Start

pip install skyspark-mcp

Create a .env file (see .env.example):

SKYSPARK_HOST=192.168.1.100
SKYSPARK_PORT=8080
SKYSPARK_PROJECT=demo
SKYSPARK_AUTH=scram
SKYSPARK_USERNAME=su
SKYSPARK_PASSWORD=your-password

Run the server:

# SSE transport (default, port 8765)
skyspark-mcp

# stdio transport (for direct MCP client integration)
skyspark-mcp --stdio

Tools

Core

Tool	Description
ss_eval	Evaluate any Axon expression
ss_about	Server info (version, project, user)
ss_read	Read records by Haystack filter
ss_read_by_id	Read a single record by ID
ss_search	Full-text search across records

CRUD

Tool	Description
ss_create	Create a new record
ss_update	Update record tags
ss_delete	Delete matching records

Functions

Tool	Description
ss_func_list	List project functions
ss_func_read	Read function source code
ss_func_commit	Update function source (base64-safe)
ss_func_commit_batch	Batch commit multiple functions
ss_func_diff	Compare current vs proposed source
ss_funcs_all	List ALL functions including built-ins

Content (base64-safe)

Tool	Description
ss_view_update	Update view source
ss_page_update	Update Docunomicon page content
ss_rec_create	Create record with complex tag values

Discovery

Tool	Description
ss_views	List views
ss_templates	List Docunomicon templates
ss_libs	List installed extensions
ss_projects	List available projects

Authentication

SCRAM (default)

Standard SkySpark authentication. Set SKYSPARK_USERNAME and SKYSPARK_PASSWORD.

No Auth

For trusted networks (Tailscale, VPN, localhost). Set SKYSPARK_AUTH=none. The server strips auth headers automatically.

Token

Pre-shared auth token. Set SKYSPARK_AUTH=token and SKYSPARK_PASSWORD=your-token.

Multi-Project

Every tool accepts an optional project and server parameter:

ss_eval(expr="readAll(site)", project="other_project")
ss_read(filter_expr="site", server="http://other-server:8080", project="demo")

Clients are pooled per server+project combination.

Usage with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "skyspark": {
      "command": "skyspark-mcp",
      "args": ["--stdio"],
      "env": {
        "SKYSPARK_HOST": "192.168.1.100",
        "SKYSPARK_PORT": "8080",
        "SKYSPARK_PROJECT": "demo",
        "SKYSPARK_AUTH": "scram",
        "SKYSPARK_USERNAME": "su",
        "SKYSPARK_PASSWORD": "your-password"
      }
    }
  }
}

Usage with mcporter

# SSE
npx mcporter call --allow-http 'http://localhost:8765/mcp.ss_eval(expr: "readAll(site)")'

# stdio
npx mcporter call --stdio "skyspark-mcp --stdio" 'ss_eval(expr: "1 + 1")'

Dependencies

• phable — Python Haystack client
• FastMCP — MCP server framework

License

MIT — built by Pip 🌱