MCP Server: Let AI Assistants Manage Sidefy

We’re adding an MCP Server to Sidefy — an experimental feature that exposes a local Model Context Protocol endpoint on your Mac. When enabled, MCP clients (such as Claude Desktop, Cursor, or Claude Code) can read and modify Sidefy configuration while the app is running.

Let AI Write Plugins and Rules for You

You no longer need to hand-write JavaScript plugins or SideScript rules from scratch. With MCP connected, describe what you want in plain language — the assistant can read Sidefy’s tool documentation, look up syntax references, and call create_custom_plugin or create_rule on your behalf.

Custom plugin example — tell your assistant something like:

Help me create a custom plugin that fetches today’s top stories from Hacker News and shows them on my timeline, one event per story with the title and link.

Event rule example — describe the filtering or styling you want:

I want to hide events whose title contains “newsletter” or “unsubscribe”, and highlight GitHub release events from sidefy-team/sidefy in green.

The assistant will use tools such as list_custom_plugins, create_custom_plugin, validate_rule, preview_rule, list_rules, and create_rule to implement your request. Review the result in Sidefy before relying on it in daily use — especially for plugins that call external APIs or rules that hide or rewrite events.

Write Events to Your Timeline

With the External Events plugin, MCP clients can also create, update, and delete persisted events on your timeline — not only read Sidefy configuration. For example, ask your assistant to block focus time for this afternoon, or let a scheduled agent drop a daily digest after it finishes compiling headlines. See External Events: Let External Tools Put Any Event on Your Timeline → for examples.

How It Works

The MCP server runs inside Sidefy and listens on localhost only:

• Transport: Streamable HTTP (MCP)
• Endpoint: http://127.0.0.1:<port>/mcp (default port 39281, configurable in Experimental Features settings)
• Authentication: Authorization: Bearer <token> on every request
• Requirement: Sidefy must stay running, and experimental features must stay enabled, while an MCP client is connected

To enable it, choose Enable Experimental Features from the Help menu, then open Experimental Features from the menu bar (under ADVANCED) and turn on MCP Server. Set Port if needed (valid range 1024–65535, default 39281), copy the token from the Connection section’s Authorization header example, and regenerate the access token from that panel.

Note: MCP Server is an experimental feature. Settings on the Experimental Features page are reset when experimental features are disabled, and the MCP server stops immediately.

Warning: AI or automated MCP clients may make incorrect changes. Review all actions after they run.

Client Setup

Before adding Sidefy in Cursor, Claude Code, or Claude Desktop:

1. In the Help menu, turn on Enable Experimental Features and confirm the warning
2. Open Experimental Features from the menu bar (under ADVANCED — this item appears only after step 1), enable MCP Server, set Port if needed, and confirm the status shows Healthy
3. Keep Sidefy running and leave experimental features enabled while the MCP client is connected
4. Copy <token> from the Connection section’s Authorization: Bearer … example; use the endpoint shown there for your client URL — update both if you change Port or regenerate the token

Cursor

Requires Cursor 0.48.0+ for Streamable HTTP. Open Cursor Settings → Tools & MCP, or edit ~/.cursor/mcp.json (project-level: .cursor/mcp.json):

{
  "mcpServers": {
    "sidefy": {
      "url": "http://127.0.0.1:39281/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

If you changed Port in Sidefy, update the URL to match the endpoint shown in the Connection section (for example http://127.0.0.1:40000/mcp).

Claude Code

Add Sidefy to .mcp.json in your project root for team sharing, or to the top-level mcpServers in ~/.claude.json for all your projects:

{
  "mcpServers": {
    "sidefy": {
      "type": "http",
      "url": "http://127.0.0.1:39281/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Or use the CLI (defaults to local scope in ~/.claude.json; add --scope project to write .mcp.json instead):

claude mcp add --scope project --transport http sidefy http://127.0.0.1:39281/mcp \
  --header "Authorization: Bearer <token>"

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "sidefy": {
      "url": "http://127.0.0.1:39281/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Do not commit real tokens to git. Prefer environment variables in client configs when supported (for example Bearer ${env:SIDEFY_MCP_TOKEN} in Cursor).

Restart the MCP client after saving the config so the new server is picked up.

Tool Reference

The server exposes 45 tools. The Description column matches what MCP clients receive from tools/list. Arguments lists each tool’s input schema (required marked with *).

Event Source Plugins

RSS Feeds

GitHub Repositories

Event Rules (SideScript)

Rule tools append a documentation hint in their MCP description. Read the syntax guides before calling write tools:

• SideScript Syntax Guide →
• SideScript 2.0: Extended TEMPLATE Syntax →

Rule Templates (SideScript)

Rule template tools append a documentation hint in their MCP description. Read the template syntax guide before calling write tools:

• SideScript 2.0: Extended TEMPLATE Syntax →

Custom JavaScript Plugins

Custom plugin tools append a documentation hint pointing to the Submit Plugin API reference and the official plugin repository (default sidefy-team/sidefy-plugins, configurable in Sidefy settings). fetchEvents(config) must be a synchronous function — not async, not a Promise. Use sidefy.http.get / sidefy.http.post for HTTP (blocking, returns response text or null). Dates must be full ISO 8601 with timezone.

Online Marketplace Plugins

Online plugin tools identify plugins only by directory_name from list_online_plugins (config-only MCP view: directoryName, isEnabled, config). Do not use test_custom_plugin or custom-plugin write tools for online plugins.

Today’s Events

External Events

External event tools append a documentation hint in their MCP description. See External Events: Let External Tools Put Any Event on Your Timeline → for usage examples. Writable tools trigger a timeline refresh; use list_today_events with source_id = com.sidecalendar.plugin.external to verify display.

Refresh

Read-only / non-refresh tools — list_*, get_*, validate_rule, validate_rule_template, preview_rule, test_custom_plugin, list_today_events, list_external_events, and get_external_event do not trigger a post-call timeline refresh. update_online_plugin_config applies config immediately but also skips the coalesced refresh path. All other write tools — including enable/disable toggles and external event create/update/delete — apply changes and then run the MCP refresh path (clear event ID cache and request a full timeline refresh). You do not need to call refresh_events after a successful write unless you want to refresh without changing configuration.

Example Workflows

With MCP connected, an assistant can:

• Add an RSS feed with custom color and icon, then confirm it in list_rss_feeds
• Toggle a feed with set_rss_feed_enabled or update its label via update_rss_feed
• Subscribe to a GitHub repo and configure event types with update_github_repo
• Validate SideScript with validate_rule, preview impact with preview_rule, then create it with create_rule
• Reorder rules with reorder_rules after listing ids via list_rules
• Create a reusable rule template with create_rule_template, then reference it from new rules
• Dry-run custom plugin code with test_custom_plugin before create_custom_plugin or update_custom_plugin
• Inspect today’s timeline with list_today_events, filtered by source_id when needed
• Block focus time or drop a briefing with create_external_event, then confirm on the timeline via list_today_events with source_id = com.sidecalendar.plugin.external
• List or edit persisted external events with list_external_events, update_external_event, or delete_external_event
• Patch a downloaded plugin’s API keys via update_online_plugin_config (merge_config=true by default; use directory_name from list_online_plugins)
• Enable or disable a built-in plugin with set_plugin_enabled

All changes go through the same validation and persistence layers as the native UI.

Share Your Thoughts

We’d love to hear how you’d use MCP with Sidefy — which tools matter most, and what additional capabilities would help your workflow.

Feel free to share ideas and feedback through GitHub Issues.

MCP Server is coming in an upcoming release as an experimental feature in the Experimental Features settings panel.