Shinzo MCP Server

A comprehensive MCP (Model Context Protocol) server for the Shinzo AI platform. This server enables AI assistants like Claude to interact with Shinzo's Spotlight analytics and agent management capabilities.

Features

• Spotlight Analytics - Access AI token usage analytics and session data
• Agent Management - Create, configure, and manage AI agents
• Agent Filesystem - Full filesystem operations for agent workspaces

Prerequisites

You'll need a Shinzo account and API key. Sign up at shinzo.ai to get started.

Installation

Option 1: Smithery Remote Server (Recommended)

Install directly via Smithery CLI:

npx -y @smithery/cli install @shinzo-labs/shinzo-mcp --client claude

Option 2: NPX Local Installation

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "shinzo": {
      "command": "npx",
      "args": ["-y", "@shinzolabs/shinzo-mcp"],
      "env": {
        "SHINZO_API_KEY": "your-api-key"
      }
    }
  }
}

Option 3: Build from Source

git clone https://github.com/shinzo-labs/shinzo-mcp.git
cd shinzo-mcp
npm install
npm run build

Then configure Claude Desktop:

{
  "mcpServers": {
    "shinzo": {
      "command": "node",
      "args": ["/path/to/shinzo-mcp/dist/index.js"],
      "env": {
        "SHINZO_API_KEY": "your-api-key"
      }
    }
  }
}

Configuration

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | SHINZO_API_KEY | Yes | - | Your Shinzo platform API key | | SHINZO_API_URL | No | https://api.shinzo.ai | Shinzo API base URL | | MCP_TRANSPORT | No | stdio | Transport mode: stdio for local MCP clients, http for Smithery/cloud deployments | | TELEMETRY_ENABLED | No | true | Enable/disable telemetry | | PORT | No | 3000 | HTTP server port (only used when MCP_TRANSPORT=http) |

Supported Tools

Spotlight Analytics (spotlight:read)

| Tool | Description | |------|-------------| | get_token_analytics | Get AI token usage analytics | | list_ai_sessions | List AI interaction sessions | | get_session_details | Get detailed session information |

Agent Management (agent:read, agent:write)

| Tool | Scope | Description | |------|-------|-------------| | list_agents | read | List all configured agents | | get_agent | read | Get agent details | | get_agent_task | read | Get task information | | create_agent | write | Create a new agent | | update_agent | write | Update agent configuration | | delete_agent | write | Delete an agent | | pause_agent | write | Pause agent execution | | resume_agent | write | Resume paused agent | | submit_agent_task | write | Submit a task to an agent | | send_task_message | write | Send message to running task | | cancel_task | write | Cancel a running task |

Agent Filesystem (agent:filesystem:read, agent:filesystem:write)

| Tool | Scope | Description | |------|-------|-------------| | read_agent_file | read | Read file contents | | list_agent_directory | read | List directory contents | | get_file_metadata | read | Get file/directory metadata | | create_agent_file | write | Create a new file | | update_agent_file | write | Update file contents | | delete_agent_file | write | Delete a file | | patch_agent_file | write | Partial file update | | create_agent_directory | write | Create a directory | | delete_agent_directory | write | Delete a directory | | copy_agent_path | write | Copy files/directories | | move_agent_path | write | Move files/directories | | search_agent_filesystem | write | Search filesystem | | create_agent_archive | write | Create archive | | extract_agent_archive | write | Extract archive | | update_file_metadata | write | Update file metadata |

Usage Examples

Manage Agents

Ask Claude: "Create a new agent called 'data-processor' with my Anthropic API key"

Check Analytics

Ask Claude: "What's my AI token usage for the past week?"

List Sessions

Ask Claude: "Show me my recent AI interaction sessions"

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Data Collection & Privacy

This MCP server includes optional telemetry to help improve the service. See PRIVACY.md for details.

License

MIT License - see LICENSE for details.