Ulysses

You can automate Ulysses on macOS using an MCP server that exposes a local API to create, read, organize, and modify your sheets. This server communicates with Ulysses through its x-callback-url API, enabling AI assistants and MCP-compatible clients to control your writing workflow directly from your preferred environment.

How to use

You connect an MCP client to the local server and start issuing tool commands to manage your Ulysses library. You can create new sheets and groups, insert text, attach notes and images, read sheet content (with authorization), and perform navigation and structural changes. Destructive actions require authorization tokens, which you obtain once from Ulysses and then reuse in subsequent requests. Start by authorizing when you need to read or modify content, then pass the resulting access token with each protected request.

Typical usage flow: authorize once, then perform create or update actions as needed. Use the server’s tools to manage your library programmatically, integrate with an AI assistant, and automate repetitive writing tasks without leaving your editor or IDE.

How to install

# Prerequisites
#  - macOS with Ulysses installed
#  - Node.js 18.0.0 or higher

# Install the MCP server package
npm install ulysses-mcp

# Build from source (optional if you pulled the repo directly)
git clone https://github.com/sonofagl1tch/ulysses-mcp.git
cd ulysses-mcp
npm install
npm run build

# Build the helper app (required for callbacks)
npm run build-helper

# Start the MCP server locally (depending on your setup, commonly you run the build output)
node /path/to/ulysses-mcp/build/index.js

Configuration and usage with MCP clients

You configure your MCP client to connect to the local server using the stdio transport. The project provides explicit examples for integrating with Claude Desktop and Cline (VS Code extension). Use the following configurations in your MCP client settings to point at the local server binary that handles callbacks and API requests.

{
  "mcpServers": {
    "ulysses": {
      "command": "node",
      "args": ["/path/to/ulysses-mcp/build/index.js"]
    }
  }
}

Usage with Claude Desktop configuration

If you use Claude Desktop, place the MCP server configuration in your Claude config path so Claude can launch the server as a local process.

{
  "mcpServers": {
    "ulysses": {
      "command": "node",
      "args": ["/path/to/ulysses-mcp/build/index.js"]
    }
  }
}

Usage with Cline (VS Code Extension) configuration

If you are using Cline, add the MCP server to your global settings so the extension can communicate with the local server.

{
  "mcpServers": {
    "ulysses": {
      "disabled": false,
      "autoApprove": [],
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/ulysses-mcp/build/index.js"]
    }
  }
}

Using other MCP clients

If you use a different MCP client, refer to its documentation for adding a stdio transport MCP server and provide the same local command path to the built index file.

Available tools

ulysses_new_sheet

Create a new sheet with provided content and optional grouping.

ulysses_new_group

Create a new group (folder) to organize sheets.

ulysses_insert

Insert or append text to an existing sheet.

ulysses_attach_note

Attach a note to a sheet.

ulysses_attach_keywords

Attach keywords (tags) to a sheet.

ulysses_attach_image

Attach an image to a sheet (base64 encoded).

ulysses_open

Open a specific sheet or group in Ulysses.

ulysses_open_all

Open the All section in Ulysses library.

ulysses_open_recent

Open sheets from the Last 7 Days.

ulysses_open_favorites

Open sheets marked as Favorites.

ulysses_get_version

Retrieve Ulysses and API version information.

ulysses_authorize

Request library access authorization for reading and other privileged actions.

ulysses_read_sheet

Read contents of a sheet (requires authorization).

ulysses_get_item

Get information about a specific sheet or group (requires authorization).

ulysses_get_root_items

Retrieve the library structure (requires authorization).

ulysses_move

Move sheets or groups to a new location (requires authorization).

ulysses_copy

Copy sheets or groups (requires authorization).

ulysses_trash

Move items to trash (requires authorization).

ulysses_set_group_title

Rename a group.

ulysses_set_sheet_title

Change the title of a sheet.

ulysses_remove_keywords

Remove keywords from a sheet.

ulysses_update_note

Update an existing note on a sheet.

ulysses_remove_note

Remove a note from a sheet.