npm package: @shinzolabs/shinzo-mcp
Description: MCP server for the Shinzo AI platform for agent orchestration and analytics
Author: Austin Born
Latest version: 0.0.0

# Shinzo MCP Server

[![npm version](https://img.shields.io/npm/v/@shinzolabs/shinzo-mcp.svg)](https://www.npmjs.com/package/@shinzolabs/shinzo-mcp)
[![GitHub stars](https://img.shields.io/github/stars/shinzo-labs/shinzo-mcp.svg)](https://github.com/shinzo-labs/shinzo-mcp/stargazers)
[![GitHub forks](https://img.shields.io/github/forks/shinzo-labs/shinzo-mcp.svg)](https://github.com/shinzo-labs/shinzo-mcp/network)
[![npm downloads](https://img.shields.io/npm/dm/@shinzolabs/shinzo-mcp.svg)](https://www.npmjs.com/package/@shinzolabs/shinzo-mcp)

A comprehensive MCP (Model Context Protocol) server for the [Shinzo AI platform](https://shinzo.ai). 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](https://shinzo.ai) to get started.

## Installation

### Option 1: Smithery Remote Server (Recommended)

Install directly via Smithery CLI:

```bash
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):

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

### Option 3: Build from Source

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

Then configure Claude Desktop:

```json
{
  "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](CONTRIBUTING.md) for guidelines.

## Data Collection & Privacy

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

## License

MIT License - see [LICENSE](LICENSE) for details.