# io.github.hermitsh-ai/shrimp (npm · @hermitsh/shrimp-mcp)

Task manager for AI agents. Zero setup, nested trees, batch ops, local-first storage.

- Trust score: 56/100 (low)
- Change this week: +18
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `@hermitsh/shrimp-mcp`: 56/100 (this document), [markdown](https://verifymcp.io/servers/hermitsh-ai-shrimp/hermitsh-shrimp-mcp.md), [page](https://verifymcp.io/servers/hermitsh-ai-shrimp/hermitsh-shrimp-mcp)

## Channel facts

- Registry: `npm`
- Package: `@hermitsh/shrimp-mcp`
- Version: `1.0.7`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 87/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (95 of 99), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (95 of 99), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 6/100
  - Repository check failed: the declared repository URL returned HTTP 404.
  - Provenance check failed: no build-provenance attestation is published.
  - License check failed: the license (UNLICENSED) isn't a recognized OSI-approved license.
  - Actively maintained (last published 117 days ago).
  - Security-disclosure policy not yet verified: we couldn't inspect the source repository.
- **Schema Quality & AI Usability**: 69/100
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 2832 tokens (~149/item across 19 items; 19 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 0/100
  - Stability not yet verified: not enough scan history yet (needs a 30-day window).
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

**Unverified: 1 category.** A category scored 0 because we could not verify it: a data source with nothing on this package, evidence we could not reach, or a check we could not run. We only credit what we can confirm.

## Install

### Claude

```bash
claude mcp add hermitsh-ai-shrimp -- npx -y @hermitsh/shrimp-mcp
```

### Codex

```bash
codex mcp add hermitsh-ai-shrimp -- npx -y @hermitsh/shrimp-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "hermitsh-ai-shrimp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@hermitsh/shrimp-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add hermitsh-ai-shrimp --command npx --arg -y --arg @hermitsh/shrimp-mcp
```

### Hermes

```yaml
mcp_servers:
  hermitsh-ai-shrimp:
    command: "npx"
    args: ["-y", "@hermitsh/shrimp-mcp"]
```

### Other

```json
{
  "mcpServers": {
    "hermitsh-ai-shrimp": {
      "command": "npx",
      "args": [
        "-y",
        "@hermitsh/shrimp-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-02 (score 56, +42)

- [security regression] Provenance: unverified → fail
- [security improvement] Install scripts: unverified → pass
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Malware scan: unverified → pass
- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [functional regression] License: unverified → fail
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] MCP protocol: unverified → pass
- [functional improvement] Schema quality: unverified → excellent
- [functional] Licence: UNLICENSED

### 2026-07-31 (score 14, −24)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-27 (score 38)

First indexed and scored.

## MCP tools (19)

### `shrimp_pair` (~262 tokens)

Pair with SHrimp

Connect this agent to a SHrimp account using a 6-digit pairing code.

The user must open the SHrimp app on their phone → Settings → Agents → Pair New Agent to generate a code. The code expires after 5 minutes.

After pairing, this agent switches from local mode to cloud mode — tasks sync to the phone in real-time. Any tasks created in local mode remain in ~/.shrimp/tasks.json but are not automatically migrated.

Args:
  \- code (string): The 6-digit numeric code from the SHrimp app.
  \- agentName (string): Display name for this agent in the app (default: "Claude").

Returns on success:
  { paired: true, email: string, agentName: string, scopes: string[], configPath: string }

Returns on failure:
  { paired: false, error: string }

Common errors:
  \- "Invalid code" → code is not exactly 6 digits
  \- "Pairing failed" → code expired or wrong. User must generate a new one.

Input parameters:

- `agentName` (string): Display name for this agent connection (shown in the SHrimp app)
- `code` (string, required): The 6-digit pairing code from the SHrimp app

### `shrimp_status` (~102 tokens)

Check SHrimp Connection

Check the current SHrimp connection mode.

Takes no arguments.

Returns one of:
  { mode: "paired", email: string, agentName: string, scopes: string[] }
  or
  { mode: "local", tasksPath: string, hint: string }

In local mode, tasks are stored on this machine in ~/.shrimp/tasks.json. All task tools work — just without phone sync. Call shrimp_pair to upgrade to cloud mode.

### `shrimp_get_tasks` (~313 tokens)

Get Task Tree

Read the user's task tree from SHrimp.

Returns all tasks as a nested hierarchy. Each task has: id, title, notes, dueDate, category, isCompleted, isArchived, and children[].

Filters (all optional):
  \- category: one of home, work, errands, health, people, money, travel, projects
  \- completed: "true" or "false" — filter by completion status
  \- archived: "true" or "false" — default is active only (false)
  \- subtree: a task ID — returns only that task and its descendants
  \- flat: "true" — returns a flat array with parentID instead of nesting

The response includes a version number. Cache this to detect changes efficiently.

Returns:
  { version: number, updatedAt: string, tasks: TaskItem[] }

TaskItem shape:
  { id: string, title: string, notes?: string, dueDate?: string, category?: string, isCompleted: boolean, isArchived: boolean, children: TaskItem[] }

Input parameters:

- `archived` (string): Filter by archive status (default: active only)
- `category` (string): Filter by category: home, work, errands, health, people, money, travel, projects
- `completed` (string): Filter by completion status
- `flat` (string): Return flat list with parentID instead of nested tree
- `subtree` (string): Task ID — return only this task and its descendants

### `shrimp_search` (~156 tokens)

Search Tasks

Search tasks by keyword. Matches against titles and notes (case-insensitive substring match).

Returns matching tasks with their full breadcrumb path so you know where they sit in the tree.

Args:
  \- q (string): Search query.
  \- limit (number): Max results, 1–50 (default: 20).

Returns:
  { results: SearchResult[], total: number }

SearchResult shape:
  { id: string, title: string, notes?: string, isCompleted: boolean, path: string[], matchField: "title" | "notes" }

Input parameters:

- `limit` (integer): Max results (default 20, max 50)
- `q` (string, required): Search query (case-insensitive substring match)

### `shrimp_add_task` (~320 tokens)

Create Task

Create a new task in SHrimp.

You can nest tasks at any depth by specifying a parentID. Use insertBefore to control ordering among siblings.

Args:
  \- title (string, required): Task title.
  \- notes (string, optional): Additional notes or details.
  \- parentID (string, optional): UUID of parent task. Omit for a root-level task.
  \- dueDate (string, optional): ISO 8601 date (e.g. "2026-04-15").
  \- category (string, optional): One of home, work, errands, health, people, money, travel, projects.
  \- insertBefore (string, optional): UUID of sibling task to insert before.

Returns:
  { ok: true, opID: string, version: number }

Tips:
  \- Use shrimp_batch for creating multiple tasks at once (up to 50 ops).
  \- UUIDs must be hex-only (0-9, a-f). Non-hex characters will be rejected.

Input parameters:

- `category` (string): Category: home, work, errands, health, people, money, travel, projects
- `dueDate` (string): ISO 8601 date string (e.g. 2026-04-15)
- `insertBefore` (string): UUID of sibling task to insert before
- `notes` (string): Additional notes or details
- `parentID` (string): UUID of parent task (omit for root-level task)
- `title` (string, required): Task title

### `shrimp_update_task` (~216 tokens)

Update Task

Update an existing task's properties. Only include the fields you want to change — omitted fields are left unchanged.

Args:
  \- taskID (string, required): UUID of the task to update.
  \- title (string, optional): New title.
  \- notes (string, optional): New notes (replaces existing notes entirely).
  \- dueDate (string, optional): New due date (ISO 8601).
  \- category (string, optional): New category (home, work, errands, health, people, money, travel, projects).

Returns:
  { ok: true, opID: string, version: number }

Input parameters:

- `category` (string): New category: home, work, errands, health, people, money, travel, projects
- `dueDate` (string): New due date (ISO 8601)
- `notes` (string): New notes (replaces existing)
- `taskID` (string, required): UUID of the task to update
- `title` (string): New title

### `shrimp_complete_task` (~80 tokens)

Toggle Task Completion

Toggle a task's completion status. If incomplete, marks it done. If already done, marks it incomplete.

Args:
  \- taskID (string, required): UUID of the task.

Returns:
  { ok: true, opID: string, version: number }

Input parameters:

- `taskID` (string, required): UUID of the task to complete/uncomplete

### `shrimp_archive_task` (~87 tokens)

Archive Task

Archive a task and all its children. Archived tasks are hidden from the main view but not deleted. Use shrimp_restore_task to bring them back.

Args:
  \- taskID (string, required): UUID of the task to archive.

Returns:
  { ok: true, opID: string, version: number }

Input parameters:

- `taskID` (string, required): UUID of the task to archive

### `shrimp_restore_task` (~68 tokens)

Restore Archived Task

Restore an archived task back to the active list.

Args:
  \- taskID (string, required): UUID of the task to restore.

Returns:
  { ok: true, opID: string, version: number }

Input parameters:

- `taskID` (string, required): UUID of the task to restore

### `shrimp_move_task` (~187 tokens)

Move Task

Move a task to a different position in the tree. Can reparent under a new task or reorder among siblings.

Args:
  \- taskID (string, required): UUID of the task to move.
  \- parentID (string, optional): UUID of new parent. Omit or null to move to root level.
  \- insertBefore (string, optional): UUID of sibling to insert before. Omit to append at end.

Returns:
  { ok: true, opID: string, version: number }

Tips:
  \- Moving a task also moves all its children.
  \- You cannot move a task under itself (circular reference).

Input parameters:

- `insertBefore` (string): UUID of sibling to insert before
- `parentID` (string): UUID of new parent (omit to move to root)
- `taskID` (string, required): UUID of the task to move

### `shrimp_delete_task` (~88 tokens)

Delete Task

Permanently delete a task and all its children. This cannot be undone.

Prefer shrimp_archive_task if you're unsure — archived tasks can always be restored.

Args:
  \- taskID (string, required): UUID of the task to delete.

Returns:
  { ok: true, opID: string, version: number }

Input parameters:

- `taskID` (string, required): UUID of the task to delete

### `shrimp_batch` (~270 tokens)

Batch Operations

Execute multiple task operations in a single request. Much more efficient than individual calls when making several changes at once.

Max 50 ops per batch. All ops are validated upfront before any are applied — if one has an invalid UUID, the entire batch is rejected.

Each op must have a "type" field. Required fields depend on the type:
  \- create: title (required), notes, parentID, dueDate, category, insertBefore
  \- update: taskID (required), title, notes, dueDate, category
  \- complete: taskID (required)
  \- archive: taskID (required)
  \- restore: taskID (required)
  \- move: taskID (required), parentID, insertBefore
  \- delete: taskID (required)

Args:
  \- ops (array): Array of operation objects (max 50).

Returns:
  { ok: true, opIDs: string[], version: number }

Tips:
  \- Use this to build entire project plans in one call.
  \- Create ops are processed in order, so you can create a parent then nest children under it in the same batch.
  \- All UUIDs must be hex-only (0-9, a-f).

Input parameters:

- `ops` (array, required): Array of operations to execute

### `shrimp_get_prompt` (~150 tokens)

Read Prompt Sections

Read the current prompt sections that control the in-app AI behavior. SHrimp's AI system prompt is modular — split into 6 editable sections that shape how the AI processes user requests.

Sections:
  \- intro: Identity and role definition
  \- rules: Behavioral rules and constraints
  \- thoroughness: How thorough/detailed the AI should be
  \- categories: Life categories for task organization (home, work, errands, health, people, money, travel, projects)
  \- schema: The JSON response schema the AI must follow
  \- terminal: Additional instructions for the terminal/chat interface

Requires the SHrimp iOS app (paired mode). Not available in local mode.

### `shrimp_update_prompt` (~147 tokens)

Update Prompt Sections

Update one or more prompt sections that control the in-app AI behavior. Partial updates are supported — only include the sections you want to change.

Sections: intro, rules, thoroughness, categories, schema, terminal

Requires the SHrimp iOS app (paired mode). Not available in local mode.

Input parameters:

- `categories` (string): Life categories for task organization
- `intro` (string): AI identity and role definition
- `rules` (string): Behavioral rules and constraints
- `schema` (string): JSON response schema the AI must follow
- `terminal` (string): Additional terminal/chat interface instructions
- `thoroughness` (string): How thorough/detailed the AI should be

### `shrimp_get_provider` (~36 tokens)

Read AI Provider/Model

Read the current AI provider and model configuration.

Requires the SHrimp iOS app (paired mode). Not available in local mode.

### `shrimp_update_provider` (~105 tokens)

Update AI Provider/Model

Change the AI provider and/or model used by SHrimp.

Requires the SHrimp iOS app (paired mode). Not available in local mode.

Input parameters:

- `modelID` (string): Model identifier (e.g. "claude-sonnet-4-20250514", "gpt-4o")
- `type` (string): AI provider type
- `useOpenAIOAuth` (boolean): Use ChatGPT OAuth instead of API key (OpenAI only)

### `shrimp_pipeline` (~87 tokens)

Read Pipeline Log

Read the processing pipeline log from the user's phone.

Requires the SHrimp iOS app (paired mode). Not available in local mode.

Pipeline stages: push, fetch, attach, batch, ai, inbox, share, file, retry

Input parameters:

- `limit` (number): Max entries to return (default 50, max 200)
- `stage` (string): Filter by pipeline stage

### `shrimp_inbox` (~103 tokens)

Read Inbox

Read the SHrimp terminal inbox.

Requires the SHrimp iOS app (paired mode). Not available in local mode.

Item sources: email, shareExtension, siri, github, clipboard, composer
Item statuses: pending, processing, processed, failed

Input parameters:

- `limit` (number): Max items to return (default 50, max 100)
- `source` (string): Filter by item source
- `status` (string): Filter by item status

### `shrimp_feedback` (~55 tokens)

Send Feedback

Send feedback to the SHrimp developer on behalf of the user. Works in both local and paired mode.

Rate limit: 5 feedback messages per hour.

Input parameters:

- `message` (string, required): Feedback message (max 2000 chars)

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/hermitsh-ai-shrimp/hermitsh-shrimp-mcp#diagnostics

## Score history

- 2026-08-03: 56
- 2026-08-02: 56
- 2026-08-01: 14
- 2026-07-31: 14
- 2026-07-30: 38
- 2026-07-28: 38
- 2026-07-27: 38

## Links

- npm package: https://www.npmjs.com/package/@hermitsh/shrimp-mcp
- Socket report: https://socket.dev/npm/package/@hermitsh/shrimp-mcp
- Changelog RSS feed: https://verifymcp.io/servers/hermitsh-ai-shrimp/hermitsh-shrimp-mcp/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/hermitsh-ai-shrimp/hermitsh-shrimp-mcp/changelog.json
- HTML version of this page: https://verifymcp.io/servers/hermitsh-ai-shrimp/hermitsh-shrimp-mcp