Inkra Mcp

Inkra MCP 服务

通过 Claude、Cursor 或任何 MCP 客户端驱动原生 macOS Markdown 编辑器。

这是 Inkra 的官方 Model Context Protocol 桥接工具。Inkra 是一款原生 macOS Markdown 编辑器（使用 SwiftUI + AppKit，而非 Electron），支持实时 KaTeX/Mermaid 预览，并内置 AI 助手。

你需要安装并运行 Inkra 应用，且拥有 Inkra Pro。 此 MCP 服务是一个 stdio→HTTP 桥接工具——Inkra 管理文档状态、撤销堆栈、语法高亮和渲染。MCP 服务和 REST API 属于 Inkra Pro 的一部分；免费试用版也包含它们。可从 store.juergenkoller.software/apps/inkra 获取 Inkra。

网站提供的 Inkra 版本已包含此桥接工具，名称为 inkra-mcp-server。在 Inkra → Settings → API 中选择 Copy MCP Config，即可获取现成配置。只有在想要审查或修改桥接工具时，才需要从此仓库构建。

---

你可以做什么

“Claude，打开 ~/Notes/2026-thesis.md，找出所有包含 ‘TODO’ 的标题，在其后添加复选框，然后保存。”

“Cursor，列出当前文件夹中的所有文件，为 H2 ‘Methodology’ 添加书签，并切换到 Focus Mode。”

MCP 服务提供 18 个工具，分为以下类别：

类别	工具
文档内容	document_get_content、document_set_content、document_insert、document_replace、document_search
文档生命周期	document_open、document_create、document_save
导航	outline_get、bookmarks_list、bookmark_add、bookmark_remove
文件夹 / 文件	folder_open、folder_list_files
元数据	frontmatter_get（YAML front-matter 解析器）
视图	theme_set（standard / sepia / night）、view_mode_set（focus / wide）
状态	window_info

每个工具都作用于 Inkra 应用中当前打开的文档——因此 AI Agent 看到的内容与你看到的完全一致，编辑会实时显示并带有语法高亮和预览，撤销/重做也会使用应用的常规撤销堆栈。

---

安装

前置条件

1. macOS 14（Sonoma）或更高版本
2. 已安装并运行 Inkra 应用——在此获取（网站版本；Mac App Store 版本不包含 MCP 服务）
3. Inkra Pro 或免费试用版——没有它，应用会对每次 MCP 调用回复 “Inkra Pro required”
4. 在 Inkra → Settings → API 中启用 API（“API Enabled”）
5. 仅在从源代码构建时需要 Swift 5.9+（Xcode 15+）

使用应用内的桥接工具（推荐）

/Applications/Inkra.app/Contents/MacOS/inkra-mcp-server

它始终与已安装的应用版本一致。

从源代码构建

git clone https://github.com/juergenkoller-software/inkra-mcp.git
cd inkra-mcp
swift build -c release
# Binary: .build/release/InkraMCP

预构建二进制文件

在 Mac 上无需使用：网站版 Inkra 已附带桥接工具（见上文）。Releases 中附带的二进制文件是适用于 Linux x86_64 的静态构建，可用于 Glama 等基于容器的 MCP 注册表；它无法在 macOS 上运行。

---

配置

Claude Desktop

{
  "mcpServers": {
    "inkra": {
      "command": "/Applications/Inkra.app/Contents/MacOS/inkra-mcp-server",
      "env": {
        "INKRA_API_PORT": "42932",
        "INKRA_API_TOKEN": "your-token-here"
      }
    }
  }
}

在 Inkra → Settings → API 中获取 INKRA_API_TOKEN，也可以在此处使用 Copy MCP Config，自动填入路径、端口和令牌。

Claude Code

claude mcp add inkra /Applications/Inkra.app/Contents/MacOS/inkra-mcp-server \
  --env INKRA_API_PORT=42932 \
  --env INKRA_API_TOKEN=your-token-here

Cursor / 其他 MCP 客户端

配置方式相同——stdio MCP 服务，使用两个环境变量。

---

工作原理

┌────────────────┐  JSON-RPC stdio   ┌────────────────┐  HTTP+Bearer   ┌────────────────┐
│  Claude/Cursor │ ───────────────►  │  InkraMCP      │ ─────────────► │  Inkra.app     │
│  (MCP client)  │ ◄───────────────  │   (this repo)  │ ◄───────────── │  (port 42932)  │
└────────────────┘                   └────────────────┘                └────────────────┘

桥接程序会将 MCP 工具调用转换为对 Inkra 本地 REST API 的请求。应用负责处理文档状态（使用 TextKit 2 的 NSTextView）、基于 AST 的语法高亮、KaTeX/Mermaid 实时预览、撤销/重做、会话恢复和导出。

---

环境变量

变量	默认值	描述
INKRA_API_PORT	42932	Inkra 本地 HTTP 服务的端口（Inkra → Settings → API）
INKRA_API_TOKEN	(none)	Inkra → Settings → API 中的 Bearer 令牌（必需）

---

错误

每次拒绝请求都会作为 MCP 错误（isError: true）返回，并附带可供 Agent 采取行动的说明：

情况	桥接程序返回的内容
Inkra 未运行，或 API 已关闭	无法通过 http://localhost:<port> 访问 Inkra；请打开 Inkra 并启用“API Enabled”
缺少令牌或令牌错误（HTTP 401）	将 INKRA_API_TOKEN 设置为 Inkra → Settings → API 中的令牌
未安装 Inkra Pro（HTTP 403 inkra_pro_required）	MCP 服务是 Inkra Pro 的一部分；只有用户可以在应用或商店中升级
其他任何 HTTP 错误	状态码和 Inkra 的错误文本

在 0.2.0 版之前，桥接程序会忽略 HTTP 状态，因此令牌错误或 Pro 功能锁定看起来像是调用成功（“OK，0 个字符”）。

---

关于 Inkra

Inkra 是一款原生 macOS Markdown 编辑器，不是 Electron 应用。特点：

• 原生体验 — SwiftUI + AppKit，提供真正的 macOS 性能
• 实时预览 — 通过 WKWebView 实时渲染 KaTeX 公式、Mermaid 图表和代码高亮
• 专注模式 + 宽屏模式 — 无干扰写作
• 内置 AI 助手 — 支持 Claude、OpenAI、Ollama 或 Inkra KI（专用端点，无需 API 密钥）
• 导出 — 导出为 HTML 和 PDF，完整保留布局、公式、图表和代码块
• 会话恢复 — 文件夹、文件、光标和滚动位置
• MCP 服务（此仓库）+ 带 Swagger UI 的 REST API — 属于 Inkra Pro 的一部分
• 支持 24 种欧盟语言
• 可在 Mac App Store 获取，也可直接下载 — MCP 服务随直接下载版提供

→ 在 store.juergenkoller.software 获取 Inkra

---

许可证

MIT — 详见 LICENSE。桥接程序开源；Inkra 应用为商业软件。

问题与支持

• 桥接程序问题： 提交问题
• 应用支持： [email protected]

由 Juergen Koller Software GmbH 构建。