Glifo Notes MCP Server

The Glifo Notes MCP Server (@glifo/notes-mcp) bridges AI coding assistants with your Glifo notes workspace. It implements the Model Context Protocol (MCP), allowing tools like Claude Code, Cursor, Windsurf, VS Code Copilot, and Zed to read, create, organize, and publish notes directly from your editor.

Architecture Overview

The system is composed of three layers:

┌─────────────────────────┐
│   AI Coding Assistant   │  Claude Code, Cursor, Windsurf, etc.
│    (MCP Client)         │
└────────────┬────────────┘
             │ stdio (JSON-RPC)
┌────────────▼────────────┐
│  @glifo/notes-mcp       │  TypeScript MCP Server (runs locally via npx)
│  16 tools / 4 groups    │
└────────────┬────────────┘
             │ HTTPS + X-API-Key
┌────────────▼────────────┐
│  Glifo Notes API        │  https://api.glifo.ai/api/v1/external/*
│  (Go backend)           │
└─────────────────────────┘

The MCP server runs as a local process spawned by your editor. It communicates with the AI assistant over stdio using JSON-RPC, and makes authenticated HTTPS calls to the Glifo external API. Your API key never leaves your machine — it's stored in your local MCP config and sent directly to the Glifo API.

Available Tools

The server exposes 16 tools across 4 groups:

Notes (5 tools)

| Tool | Description | |------|-------------| | create_note | Create a note with markdown content. Optionally assign to a folder or project. | | list_notes | List all notes with metadata (title, ID, folder, project). | | get_note | Retrieve a note by ID with full markdown content. | | update_note | Update title and/or content of an existing note. | | delete_note | Permanently delete a note. |

Folders (5 tools)

| Tool | Description | |------|-------------| | create_folder | Create a folder to organize notes. Supports nesting via parent_id. | | list_folders | List all folders with names, IDs, and parent relationships. | | get_folder | Get folder details by ID. | | update_folder | Rename a folder. | | delete_folder | Delete a folder and all its contents. |

Publishing (4 tools)

| Tool | Description | |------|-------------| | publish_note | Publish a note to your site. Generates a public URL from your subdomain + slug. | | unpublish_note | Remove a note from public access (content is preserved). | | republish_note | Update a published note with its latest content. | | list_published_notes | List published notes with slugs, URLs, and view counts. |

Projects (2 tools)

| Tool | Description | |------|-------------| | list_projects | List all your projects (sites) with subdomains. | | get_project | Get project details including subdomain, type, and public URL. |

Setup

1. Get an API Key

Create an API key from the Glifo app under Settings > API Keys. Make sure the key has the scopes you need:

• notes:read — read notes and projects

• notes:write — create, update, delete notes

• folders:read — read folders

• folders:write — create, update, delete folders

• publish:write — publish, unpublish, republish notes

2. Configure Your Editor

Claude Code — add to .claude/settings.json:

{
  "mcpServers": {
    "glifo-notes": {
      "command": "npx",
      "args": ["-y", "@glifo/notes-mcp"],
      "env": {
        "GLIFO_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "glifo-notes": {
      "command": "npx",
      "args": ["-y", "@glifo/notes-mcp"],
      "env": {
        "GLIFO_API_KEY": "your-api-key"
      }
    }
  }
}

The same config structure works for any MCP-compatible client.

3. Start Using It

Once configured, restart your editor. The AI assistant will automatically discover the tools. You can then ask things like:

• "List my notes"

• "Create a note about deployment best practices"

• "Publish the getting-started note with slug getting-started"

• "Move that note into the API Reference folder"

Configuration Reference

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | GLIFO_API_KEY | Yes | — | Your Glifo API key | | GLIFO_API_URL | No | https://api.glifo.ai | API base URL (for self-hosted instances) | | REQUEST_TIMEOUT_MS | No | 30000 | Request timeout in milliseconds |

How It Works Under the Hood

1. Your editor spawns the MCP server as a child process using npx -y @glifo/notes-mcp

2. The server reads GLIFO_API_KEY from its environment and initializes an HTTP client

3. It registers all 16 tools with the MCP SDK and connects via stdio transport

4. When you ask the AI to perform a notes operation, the assistant calls the appropriate tool

5. The server translates the tool call into an HTTPS request to api.glifo.ai/api/v1/external/*

6. Markdown content is sent as-is — the Glifo backend handles conversion to its internal Tiptap JSON format

7. Results are formatted as readable text and returned to the assistant

All note content flows as markdown — you never need to deal with the underlying Tiptap JSON. The server handles the content_format: "markdown" flag automatically on every write operation.