npm package: @swarmrise/mcp-server
Description: Swarmrise MCP server -- exposes organizational data to AI agents via the Model Context Protocol
Latest version: 0.1.0

# Swarmrise MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes Swarmrise organizational data to AI agents.

## Setup

### Prerequisites

- A Swarmrise API key (`swrk_*`) -- create one from the Swarmrise web app under the API Keys page
- The Convex site URL for your Swarmrise deployment
- The organization ID you want the agent to access

### Install

```bash
npm install -g @swarmrise/mcp-server
```

### Configure Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "swarmrise": {
      "command": "swarmrise-mcp",
      "env": {
        "SWARMRISE_API_KEY": "swrk_your_key_here",
        "SWARMRISE_SITE_URL": "https://your-deployment.convex.site",
        "SWARMRISE_ORGA_ID": "your_orga_id_here"
      }
    }
  }
}
```

### Or use npx (no install)

```json
{
  "mcpServers": {
    "swarmrise": {
      "command": "npx",
      "args": ["-y", "@swarmrise/mcp-server"],
      "env": {
        "SWARMRISE_API_KEY": "swrk_your_key_here",
        "SWARMRISE_SITE_URL": "https://your-deployment.convex.site",
        "SWARMRISE_ORGA_ID": "your_orga_id_here"
      }
    }
  }
}
```

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `SWARMRISE_API_KEY` | Yes | Your `swrk_*` API key |
| `SWARMRISE_SITE_URL` | Yes | Convex site URL (e.g., `https://xxx.convex.site`) |
| `SWARMRISE_ORGA_ID` | Yes | Organization ID to scope all operations |

## Resources

The server exposes the following read-only resources:

| Resource | URI Pattern | Description |
|----------|------------|-------------|
| Organization | `swarmrise://orgas/{orgaId}` | Org details |
| Members | `swarmrise://orgas/{orgaId}/members` | All org members |
| Teams | `swarmrise://orgas/{orgaId}/teams` | All teams |
| Roles | `swarmrise://orgas/{orgaId}/roles` | All roles |
| Channels | `swarmrise://orgas/{orgaId}/channels` | Accessible channels |
| Messages | `swarmrise://orgas/{orgaId}/channels/{channelId}/messages` | Channel messages |
| Decisions | `swarmrise://orgas/{orgaId}/decisions` | Audit trail |
| Policies | `swarmrise://orgas/{orgaId}/policies` | Organization policies |
| Invitations | `swarmrise://orgas/{orgaId}/invitations` | Invitations |
| Kanban Board | `swarmrise://orgas/{orgaId}/teams/{teamId}/board` | Team Kanban |
| Notifications | `swarmrise://orgas/{orgaId}/notifications` | Notifications |
| Meetings | `swarmrise://orgas/{orgaId}/teams/{teamId}/meetings` | Upcoming meetings |
| Past Meetings | `swarmrise://orgas/{orgaId}/teams/{teamId}/meetings/completed` | Completed meetings |
| Meeting | `swarmrise://orgas/{orgaId}/meetings/{meetingId}` | Single meeting |
| Meeting Agenda | `swarmrise://orgas/{orgaId}/meetings/{meetingId}/agenda` | Agenda items |
| Webhooks | `swarmrise://orgas/{orgaId}/webhooks` | Webhook endpoints |

## Tools

| Tool | Description |
|------|-------------|
| `ping` | Health check |
| `search_policies` | Search policies by title/abstract |
| `list_decisions` | List decisions with optional team/type filters |
| `get_messages` | Fetch channel messages with pagination |
| `list_invitations` | List invitations with optional status filter |

## Prompts

| Prompt | Description |
|--------|-------------|
| `governance_context` | Full org overview: teams, members, roles, policies, recent decisions |
| `policy_review` | All policies formatted for review |
| `team_overview` | Deep dive into a team: roles, meetings, board |
| `meeting_prep` | Prepare for a meeting: agenda, recent decisions |

## Security

- The MCP server inherits the permissions of the API key. It can only access data the key's scopes allow.
- API keys are org-scoped and member-scoped. The server cannot access data outside the configured organization.
- Rate limiting is enforced by the Swarmrise API (100 requests/minute per key).
- DM channels are accessible only if the API key's member is a participant.