# @myhero/mcp-server

MCP server for [HERO](https://app.myhero.so) — lets AI tools like **Claude Desktop**, **Cursor**, **Claude Code**, and any stdio MCP client read and write your HERO documents, projects, and tables.

## Quick start

Add it to your AI tool's MCP config:

```json
{
  "mcpServers": {
    "hero": {
      "command": "npx",
      "args": ["-y", "@myhero/mcp-server"],
      "env": {
        "HERO_API_KEY": "hero_at_your_token_here"
      }
    }
  }
}
```

Generate the token at [app.myhero.so](https://app.myhero.so) → **Settings → MCP Tokens**.

For step-by-step setup with Claude Desktop, Cursor, Claude Code, and others, see the **[full guide at myhero.so/mcp-setup](https://myhero.so/mcp-setup)**.

## What it does

**Documents**
- Read any document — full content, plain text, metadata, or just the section titles
- Search across all your workspaces and projects
- Create new documents, rename, move, duplicate, or delete them
- Take snapshots, list every block in a document, jump to a section by its numbering
- Surgical edits: change a single paragraph, heading, list item, or table without rewriting the rest with full HERO block schema.

**Clauses & legal structure**
- Read, list, and edit clauses, sub-clauses, and definitions inside contracts and agreements
- Find every document that references a given clause or defined term
- Pull a definition's explanation directly from the document that owns it

**Projects, folders, and workspaces**
- List your workspaces, projects, folders, and the documents inside them
- Create projects, rename them, organize documents into folders
- Move or copy documents between projects in bulk

**Tables**
- Create tables, add or remove columns and rows, set dynamic values.
- Read whole tables, look up specific rows, columns, or cells by name
- Update cells one at a time or in batch
- Reference rows from inside documents so the document stays in sync with the table

**Templates & placeholders**
- Build reusable document templates with live placeholders that pull from your tables
- When the underlying table data changes, every document that references it updates automatically

## Authentication

Two ways to authenticate:

1. **Personal access token** (`HERO_API_KEY` env var) — recommended for headless setups.
2. **OAuth login** — omit the env var and the bridge opens your browser on first use. Tokens are saved to `~/.hero/credentials.json`.

Manage and revoke tokens or sessions at [app.myhero.so](https://app.myhero.so) → **Settings → MCP Tokens**.

## Environment variables

| Variable | Default | Purpose |
|---|---|---|
| `HERO_API_KEY` | *(unset)* | Skip OAuth — use a personal access token |
| `HERO_API_URL` | `https://app.myhero.so` | Override the API base URL (for self-hosted / staging) |
| `HERO_APP_URL` | `https://app.myhero.so` | Override the app base URL used during OAuth login |

## Source

Source lives at [github.com/Unwynd-io/hero-mcp](https://github.com/Unwynd-io/hero-mcp). Issues and pull requests welcome.