npm package: @glifo/notes-mcp
Description: MCP server for Glifo Notes — manage notes, folders, and publishing for AI agents
Latest version: 0.1.0

# @glifo/notes-mcp

MCP server for [Glifo](https://glifo.ai) -- manage notes, folders, and publishing on Glifo sites.

Exposes the Glifo Notes API as 16 MCP tools across 4 groups. Works with Claude Code, Cursor, Windsurf, VS Code Copilot, Zed, and any MCP-compatible client. All note content is always in **markdown format**.

## Quick Start

Add to your MCP client config:

**Claude Code** (`.claude.json`):
```json
{
  "mcpServers": {
    "glifo-notes": {
      "command": "npx",
      "args": ["-y", "@glifo/notes-mcp"],
      "env": {
        "GLIFO_API_KEY": "your-api-key"
      }
    }
  }
}
```

**Cursor** (`.cursor/mcp.json`):
```json
{
  "mcpServers": {
    "glifo-notes": {
      "command": "npx",
      "args": ["-y", "@glifo/notes-mcp"],
      "env": {
        "GLIFO_API_KEY": "your-api-key"
      }
    }
  }
}
```

**Generic MCP** (any compatible client):
```json
{
  "command": "npx",
  "args": ["-y", "@glifo/notes-mcp"],
  "env": {
    "GLIFO_API_KEY": "your-api-key",
    "GLIFO_API_URL": "https://api.glifo.ai"
  }
}
```

## Tools

### Notes

| Tool | Description |
|------|-------------|
| `create_note` | Create a new note. Content must be markdown format. Optionally place it in a folder or project. |
| `list_notes` | List all notes with metadata (title, ID, folder, project, publish status) without full content. |
| `get_note` | Get a single note by ID, including its full markdown content. |
| `update_note` | Update a note's title and/or content. Content must be markdown format. |
| `delete_note` | Delete a note permanently. |

### Folders

| Tool | Description |
|------|-------------|
| `create_folder` | Create a new folder to organize notes into sections. Supports nesting via parent_id. |
| `list_folders` | List all folders with names, IDs, parent relationships, and positions. |
| `get_folder` | Get a single folder by ID, including its metadata. |
| `update_folder` | Rename a folder. |
| `delete_folder` | Delete a folder and all its contents (notes and subfolders). |

### Publishing

| Tool | Description |
|------|-------------|
| `publish_note` | Publish a note to make it publicly accessible via the project subdomain. |
| `unpublish_note` | Remove a note from public access. Content is preserved but no longer publicly visible. |
| `republish_note` | Update a published note with its latest content. Use instead of unpublish + publish. |
| `list_published_notes` | List all published notes with their slugs, URLs, and view counts. |

### Projects

| Tool | Description |
|------|-------------|
| `list_projects` | List all projects (sites). Each project has a subdomain (e.g., docs.glifo.ai). |
| `get_project` | Get project details including subdomain, type, and public URL. |

## Configuration

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `GLIFO_API_KEY` | Yes | -- | API key for Glifo |
| `GLIFO_API_URL` | No | `https://api.glifo.ai` | Glifo API base URL |
| `REQUEST_TIMEOUT_MS` | No | `30000` | Request timeout in milliseconds |

### Required API Key Scopes

Your API key must have the following scopes depending on which tools you use:

- `notes:read` -- list_notes, get_note
- `notes:write` -- create_note, update_note, delete_note
- `folders:read` -- list_folders, get_folder
- `folders:write` -- create_folder, update_folder, delete_folder
- `publish:write` -- publish_note, unpublish_note, republish_note, list_published_notes

Project tools (`list_projects`, `get_project`) require `notes:read`.

## Companion Skill

After installing, export the companion Claude Code skill for richer agent behavior:

```bash
npx agents export --target claude
```

This generates a `.claude/skills/` directory with instructions that help the agent use the tools more effectively.

## Development

```bash
npm install
npm run build        # Compile TypeScript
npm run dev          # Run with tsx (hot reload)
npm run inspector    # Open MCP Inspector UI
```

## License

MIT