Sakura-MCP-Server

Sakura-MCP-Server is a secure remote MCP gateway for Life Dashboard, Home Assistant, and DSH. The service is built on the official MCP TypeScript SDK v2 and provides a Streamable HTTP endpoint: https://your-domain/mcp.

Current Capabilities

• Dual authentication with Bearer API Key and Authentik JWT (OIDC); both share the same scope permission model.

• RFC 9728 Protected Resource Metadata: /.well-known/oauth-protected-resource/mcp.

• Per-request stateless MCP transport: authentication and tool permissions are never reused across client sessions.

• Business tools are only registered when the corresponding Adapter is configured:

  • Home Assistant: query entity states, control whitelisted entities, activate whitelisted scenes;

  • Life Dashboard internal API: read life overview, DSH workspace summary, send DSH follow-up;

  • JSON Lines audit log.

• Docker, Nginx, GitHub CI, and automatic GitHub Release creation on v* tags.

Home Assistant Token, Authentik Token, DSH pairing keys, and the server Shell are never exposed to Agents.

Related MCP server: Home Assistant MCP Server

Local Startup

Requires Node.js 22+. If Windows PowerShell blocks npm.ps1, use npm.cmd.

cd D:\Sakura-MCP-Server
Copy-Item .env.example .env
# 编辑 .env：至少替换 PUBLIC_BASE_URL 和 MCP_API_KEYS 中的示例 secret
npm.cmd install
npm.cmd run check
npm.cmd run build
npm.cmd start

Verify the health check:

Invoke-RestMethod http://127.0.0.1:3000/health

API Key Format and Scope

MCP_API_KEYS is a comma-separated list of entries in the format:

MCP_API_KEYS=cline-prod:一个至少32字节的随机密钥:life:read|home:read|dsh:summary,automation:另一个随机密钥:home:control

Generate a key:

node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"

Available scopes: life:read, home:read, home:control, todo:read, todo:write, dsh:summary, dsh:details, dsh:followup.

Clients need to fill in the MCP remote service settings:

URL: https://mcp.example.com/mcp
Authorization: Bearer <分配给该 Agent 的密钥>

Different Agents have different UI configuration fields; as long as it supports Streamable HTTP MCP with an Authorization request header, the URL above will work. Create a separate API Key for each Agent, granting only the required scopes.

Authentik OIDC / OAuth

Once AUTHENTIK_ISSUER, AUTHENTIK_AUDIENCE, and AUTHENTIK_JWKS_URI are fully configured, the service validates the JWT's issuer, audience, expiration time, and signature; the standard scope claim (or the claim specified by AUTHENTIK_SCOPE_CLAIM) is mapped to MCP scopes.

The current implementation is an MCP Resource Server that accepts Bearer JWTs issued by Authentik with an audience dedicated to the MCP service. Remote OAuth clients also need to create an OAuth 2.1 Provider in Authentik, enabling Authorization Code + PKCE, exact redirect URI, scope mapping, and audience. Do not forward received MCP user JWTs to Home Assistant or Life Dashboard; Adapters must use their own service credentials.

Business Adapter Configuration

Home Assistant

Set HOME_ASSISTANT_URL and a dedicated least-privilege Token. Write operations are only registered/succeed when the corresponding resource is explicitly listed in the whitelist variables:

HOME_ASSISTANT_CONTROLLABLE_ENTITIES=light.living_room,switch.coffee_machine
HOME_ASSISTANT_ALLOWED_SCENES=scene.good_night

Life Dashboard / DSH

The existing config.php is a browser OIDC gateway and cannot be called by the MCP Server impersonating a browser. Please add a dedicated internal service API to Life Dashboard later, using an independent service token and keeping the returned fields minimal. This project reserves:

GET  /internal/mcp/overview
GET  /internal/mcp/dsh/workspaces
POST /internal/mcp/dsh/followups

The corresponding tools are only registered after configuring LIFE_DASHBOARD_INTERNAL_URL and LIFE_DASHBOARD_INTERNAL_TOKEN. DSH should continue to use the existing one-time pairing, HMAC, anti-replay, explicit detail authorization, 8,000-character, and 120-second command queue limits.

Docker and Nginx Deployment

On the server:

cp .env.example .env
# 填写真实配置，并 chmod 600 .env
mkdir -p data
docker compose up -d --build

The container binds only to the server's local 127.0.0.1:3000 by default. Use nginx-mcp.conf.example to configure an HTTPS reverse proxy, and the Authorization request header must be preserved. In production, only expose 443; do not expose 3000 directly.

Release

Pushing to main runs type checking, unit tests, and Docker builds. Creating and pushing a semantic tag automatically runs tests, npm pack, and creates a GitHub Release:

git tag v0.1.0
git push origin v0.1.0

Current Limitations and Next Steps

The first version already completes the MCP protocol, authentication, permissions, HA adapter, and deployment skeleton. Once you provide the server domain, Authentik Provider information, and the Life Dashboard internal API, the next steps will complete real OAuth browser authorization interoperability testing, the Life Dashboard PHP internal API, To Do/calendar tools, and production deployment validation.