Shelly API Docs MCP Server

BETA

This MCP server is currently in beta. Features and tools may change.

The Shelly API Docs MCP Server gives AI assistants direct access to the complete Shelly IoT device API documentation. It implements the Model Context Protocol (MCP) — an open standard that lets AI agents interact with external tools and data sources.

When connected, your AI assistant can search documentation, look up API methods, list devices, generate code examples, and more — all without you having to copy-paste from the docs.

Server URL

https://shelly-api-docs.mcp.shelly.link/mcp

This is a remote MCP server using Streamable HTTP transport. No local installation is required — just point your AI tool to the URL above.

Available Tools

The server exposes 7 tools that AI assistants can call:

Tool	Description
search_docs	Full-text search across all Shelly API documentation. Supports filtering by section (gen2, docs-ble, integrator-api, cloud-control-api) and document type (component, device, guide, reference, addon, integration)
search_changelog	Search the firmware changelog for specific changes, fixes, or features. Supports filtering by firmware version and change type (fixed, added, changed, removed, deprecated)
get_document	Retrieve the full content of a specific documentation page by its path
get_api_method	Get detailed documentation for a specific API method (e.g., Switch.Set, Shelly.GetStatus), including parameters and response format
list_devices	List Shelly devices with optional filtering by generation (gen2, gen3, gen4), product line, or supported component
list_methods	List all available API methods for a specific component (e.g., all methods under Switch, Cover, WiFi)
get_example	Get code examples for a specific API method in HTTP URL, curl, or mos format

Available Resources

The server provides 4 read-only resources:

Resource URI	Description
shelly://docs	Index of all documentation files with metadata
shelly://methods	Index of all available API methods
shelly://devices	List of all Shelly devices with their supported components
shelly://components	List of all API component names

Available Prompts

The server includes 3 built-in prompts that help AI assistants structure their responses:

Prompt	Arguments	Description
api_help	topic (required)	Get help with a specific API method or component
device_setup	device (required)	Get setup guidance for a specific Shelly device
code_example	action (required), language (optional)	Generate a code example for a specific action

Setup Guides

Claude Desktop

1. Open your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add the Shelly MCP server:

{
  "mcpServers": {
    "shelly-api-docs": {
      "type": "url",
      "url": "https://shelly-api-docs.mcp.shelly.link/mcp"
    }
  }
}

3. Restart Claude Desktop. You should see the Shelly tools available in the tools menu (hammer icon).

---

Cursor

1. Open your project's .cursor/mcp.json file (create it if it doesn't exist), or the global config at ~/.cursor/mcp.json:

{
  "mcpServers": {
    "shelly-api-docs": {
      "type": "url",
      "url": "https://shelly-api-docs.mcp.shelly.link/mcp"
    }
  }
}

2. Restart Cursor or reload the window. The Shelly tools will appear in Settings > MCP.

---

VS Code / GitHub Copilot

1. Open your workspace .vscode/mcp.json file (create it if it doesn't exist):

{
  "servers": {
    "shelly-api-docs": {
      "type": "http",
      "url": "https://shelly-api-docs.mcp.shelly.link/mcp"
    }
  }
}

Alternatively, add it to your user settings.json:

{
  "mcp": {
    "servers": {
      "shelly-api-docs": {
        "type": "http",
        "url": "https://shelly-api-docs.mcp.shelly.link/mcp"
      }
    }
  }
}

2. Restart VS Code. The Shelly tools will be available to GitHub Copilot in agent mode.

---

Windsurf

1. Open the Windsurf MCP configuration file at ~/.codeium/windsurf/mcp_config.json (create it if it doesn't exist):

{
  "mcpServers": {
    "shelly-api-docs": {
      "serverUrl": "https://shelly-api-docs.mcp.shelly.link/mcp"
    }
  }
}

2. Restart Windsurf. The Shelly tools will appear in the Cascade panel.

---

ChatGPT

ChatGPT supports custom MCP servers through the Apps feature (beta):

1. Open chatgpt.com
2. Click Apps in the sidebar
3. Click the settings/gear icon
4. Click New App
5. Fill in the details:
   • Name: Shelly API Docs
   • Description: Search Shelly IoT device API documentation
   • MCP Server URL: https://shelly-api-docs.mcp.shelly.link/mcp
   • Authentication: Select None
6. Check the acknowledgment checkbox and click Create

The Shelly tools will now be available in your conversations.

For developers using the OpenAI Responses API, you can connect to the MCP server programmatically:

{
  "type": "mcp",
  "server_label": "shelly-api-docs",
  "server_url": "https://shelly-api-docs.mcp.shelly.link/mcp",
  "require_approval": "never"
}

See the OpenAI MCP documentation for full details.

---

Other MCP-Compatible Clients

For any MCP-compatible client (Continue.dev, Cline, Zed, etc.), use the following configuration:

• Transport type: Streamable HTTP
• URL: https://shelly-api-docs.mcp.shelly.link/mcp
• Authentication: None required
• Headers: None required

Continue.dev

Add to your ~/.continue/config.yaml:

mcpServers:
  - name: shelly-api-docs
    url: https://shelly-api-docs.mcp.shelly.link/mcp

Cline

Add to your Cline MCP settings (accessible via the Cline sidebar in VS Code):

{
  "mcpServers": {
    "shelly-api-docs": {
      "url": "https://shelly-api-docs.mcp.shelly.link/mcp"
    }
  }
}

Health Check

You can verify the server is running by visiting:

https://shelly-api-docs.mcp.shelly.link/mcp/health

This returns a JSON response with the server status, version, and number of indexed documents.

Example Usage

Once connected, you can ask your AI assistant questions like:

• "How do I turn on a Shelly switch using the API?"
• "What components does the Shelly Pro 4PM support?"
• "Show me a curl example for setting the WiFi configuration"
• "What changed in firmware version 1.4.0?"
• "How does authentication work on Shelly Gen2+ devices?"

The AI assistant will automatically use the MCP tools to search the documentation and provide accurate, up-to-date answers.