Skip to main content
Glama
deenzh
sschmitt-cg

scrivener-mcp

by sschmitt-cg
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

scrivener-mcp

一个本地 MCP 服务器，将您的 Scrivener 项目暴露给 Claude（或任何兼容 MCP 的客户端）。无需打开 Scrivener，即可从零开始创建项目、导航大纲、读写文档内容并更新元数据。

要求

  • Node.js 18 或更高版本

  • macOS 上的 Scrivener 3 (.scriv 包)

Related MCP server: Mac MCP

设置

cd scrivener-mcp
npm install

环境变量

变量

描述

SCRIV_DIR

包含 .scriv 包的目录路径。启用 list_projects、open_project 和 create_project。

SCRIV_PATH

单个 .scriv 包的路径。启动时立即打开它。

SCRIV_PLATFORM

mac（默认）或 windows。控制写入文档内容时使用的 RTF 格式。

必须至少设置 SCRIV_DIR 或 SCRIV_PATH 中的一个。两者也可以同时设置。

手动运行

# Multi-project mode (recommended)
SCRIV_DIR="/path/to/ScrivenerProjects" npm start

# Single-project mode
SCRIV_PATH="/path/to/MyProject.scriv" npm start

配置 Claude Desktop

编辑 Claude Desktop 配置文件：

  • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Mac:

{
  "mcpServers": {
    "scrivener": {
      "command": "node",
      "args": ["/absolute/path/to/scrivener-mcp/src/index.js"],
      "env": {
        "SCRIV_DIR": "/Users/you/Writing/ScrivenerProjects"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "scrivener": {
      "command": "node",
      "args": ["C:\\path\\to\\scrivener-mcp\\src\\index.js"],
      "env": {
        "SCRIV_DIR": "C:\\Users\\you\\Documents\\ScrivenerProjects",
        "SCRIV_PLATFORM": "windows"
      }
    }
  }
}

保存后重启 Claude Desktop。

可用工具

项目管理

工具

描述

list_projects

列出 SCRIV_DIR 中的所有 .scriv 包。

open_project(name)

按名称打开项目，使其成为所有文档工具的活动项目。

create_project(name, ...)

创建一个新项目并打开它。详见下文。

文档工具（需要打开项目）

工具

描述

get_outline

以嵌套树的形式返回完整大纲，包含概要、标签和状态。这是理解和处理项目结构的最佳起点。

list_documents

以带有深度指示的扁平列表形式返回大纲。对于获取 UUID 非常有用。

get_document(uuid)

返回单个文档的元数据和纯文本内容。

add_document(...)

向大纲中添加新文档或文件夹。

move_document(uuid, newParentUuid)

将大纲项移动到不同的父文件夹。

write_document(uuid, content)

将新的纯文本内容写入文档（存储为 RTF）。

update_metadata(uuid, changes)

更新标题、概要、标签、状态或编译包含项。

search_documents(query)

在整个大纲中搜索标题和概要。

创建项目

create_project 接受完整的大纲结构，因此 Claude 可以通过一次调用从构思中构建整个项目。

参数

参数

类型

描述

name

string

项目名称（成为 .scriv 包的名称）。

labels

array

标签定义。每个都是字符串或 {name, color}。颜色：red, orange, yellow, green, blue, purple, pink, cyan。

statuses

array

状态名称。默认为：To Do, In Progress, First Draft, Revised Draft, Done。

manuscript

array

草稿（手稿）文件夹中的大纲项。

research

array

研究文件夹中的大纲项。

大纲项结构

{
  "title": "Chapter 1",
  "type": "Folder",
  "synopsis": "Alice finds the letter and confronts Bob.",
  "content": "Optional initial body text (Text items only).",
  "label": "POV: Alice",
  "status": "To Do",
  "includeInCompile": true,
  "children": [...]
}

  • type: 容器（幕、部分、章节）为 "Folder"；文档（场景、笔记）为 "Text"。默认为 "Text"。

  • synopsis: 虚拟索引卡文本 — 出现在 Scrivener 的软木板和大纲视图中。写 1-3 句关于发生了什么或该项涵盖内容的摘要。

  • label 和 status 必须与项目 labels 和 statuses 数组中定义的名称匹配。

示例

{
  "name": "My Novel",
  "labels": [
    { "name": "POV: Alice", "color": "blue" },
    { "name": "POV: Bob", "color": "red" }
  ],
  "statuses": ["To Do", "First Draft", "Revised", "Done"],
  "manuscript": [
    {
      "title": "Act One",
      "type": "Folder",
      "synopsis": "Alice discovers the conspiracy.",
      "children": [
        {
          "title": "Chapter 1",
          "type": "Folder",
          "synopsis": "A normal Tuesday turns strange.",
          "children": [
            {
              "title": "The Letter",
              "type": "Text",
              "synopsis": "Alice finds an unsigned letter in her mailbox.",
              "label": "POV: Alice",
              "status": "To Do"
            }
          ]
        }
      ]
    }
  ],
  "research": [
    {
      "title": "Characters",
      "type": "Folder",
      "children": [
        {
          "title": "Alice",
          "type": "Text",
          "synopsis": "Protagonist. Mid-30s journalist, sceptical but curious."
        }
      ]
    }
  ]
}

协作工作流

预期的模式是与 Claude 一起使用 Scrivener 自身的组织功能来处理项目的结构和内容：

  1. 从 get_outline 开始 — Claude 在建议或进行任何更改之前读取带有概要的完整嵌套结构。这就是它理解故事形态的方式。

  2. 使用 add_document 构建结构 — 在层次结构的任何位置添加场景、章节、幕或研究笔记。始终包含概要；它会出现在 Scrivener 软木板的索引卡上。

  3. 使用 move_document 重新组织 — 在父级之间移动项目以重构叙事，而不会丢失任何内容或元数据。

  4. 使用 write_document 撰写正文 — 一旦结构达成一致，就用内容填充场景。

  5. 使用 update_metadata 跟踪进度 — 随着工作的进展，更新标签（例如 POV、场景类型）和状态（例如 First Draft, Revised）。

注意事项

  • 写入前关闭 Scrivener。 write_document、update_metadata、add_document 和 move_document 都会直接修改项目文件。如果 Scrivener 打开了该项目，它会在下次自动保存时覆盖更改。

  • 在 Scrivener 中编辑后重新加载。 再次调用 open_project 以重新加载在服务器运行期间在 Scrivener 中修改过的项目。

  • write_document 生成与 Scrivener 3 兼容的最小 RTF。非 ASCII 字符会被 Unicode 转义。

  • 标签和状态 ID 可通过 list_documents 发现 — labelId/statusId 是原始 ID，label/status 是解析后的名称。

This server cannot be deployed

Pay for results, not tokens.Fund a bounty. Let AI agents compete and collaborate to solve your problems.agentbounties.appAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • macos-mcp

    CursorTouch
    A
    license
    Not graded
    quality
    A
    maintenance
    A lightweight MCP server that bridges AI agents and macOS, enabling automation of file navigation, application control, UI interaction, browser automation, and system operations.
    203
    MIT

  • Mac MCP

    bulutarkan
    A
    license
    Not graded
    quality
    A
    maintenance
    Open-source, local macOS MCP server for AI agents. Automate background Safari/Chrome tabs, native apps, files and shell with scoped permissions, optional approvals and delegated coding agents.
    83
    MIT