Name: 文档管理OCR服务
Author: readur

使用说明

读取MCP服务器

一个MCP（模型上下文协议）服务器，公开Readur的文档管理和OCR API作为人工智能助手的工具。此服务器使Claude Code、Claude Desktop和其他MCP兼容应用程序等AI客户端能够列出、搜索、读取、上传和组织存储在Readur实例中的文档。

主控程序是一个开放协议，规范了人工智能应用程序与外部工具和数据源的交互方式。通过运行此服务器，您可以让您的AI助手通过18个专门构建的工具直接访问您的Readur文档库。

特性

文档管理 --列出、检查、上传、删除和重新处理具有完整元数据访问权限的文档，包括OCR提取的文本。

全文检索 --使用相关性评分、文本片段、按MIME类型和状态过滤以及查询建议在文档内容中搜索。

标签组织 --创建标签并将其分配给文档进行分类和检索。

系统监控 --检查经过身份验证的用户信息、应用程序设置、OCR语言可用性和处理队列统计信息。

工具摘要

类别	工具
文件	`list_documents`, `get_document`, `get_document_ocr_text`, `upload_document`, `delete_document`, `retry_document_ocr`
搜索	`search_documents`, `enhanced_search`, `get_search_facets`
标签	`list_labels`, `create_label`, `get_document_labels`, `add_document_label`, `remove_document_label`
状态	`whoami`, `get_settings`, `get_queue_stats`, `get_ocr_languages`

先决条件

Node.js>=24.0.0
正在运行的Readur实例 具有API访问权限
认证凭证：JWT令牌或用户名/密码对

安装

克隆存储库并从源代码构建：

git clone <repository-url>
cd readur-mcp
npm install
npm run build

构建后，编译后的服务器位于 dist/index.js.

配置

服务器接受来自三个来源的配置，按以下优先级顺序（从高到低）应用：

CLI参数
环境变量
配置文件 (~/.config/readur-mcp/config.json)

通过CLI参数设置的值会覆盖通过环境变量设置的相同值，而环境变量又会覆盖配置文件。

环境变量

变量	必填	描述
`READUR_URL`	是	Readur实例的基本URL（无尾随斜线）
`READUR_TOKEN`	否*	预先获得的JWT身份验证令牌
`READUR_USERNAME`	否*	基于登录的身份验证用户名
`READUR_PASSWORD`	否*	基于登录的身份验证密码
`READUR_TRANSPORT`	否	运输类型： `stdio` （默认）或 `sse`

*您必须提供 READUR_TOKEN 或两者 READUR_USERNAME 和 READUR_PASSWORD.

CLI参数

--url <url>               Readur server URL (required, no trailing slash)
--token <token>           Pre-obtained JWT authentication token
--username <username>     Username for login-based authentication
--password <password>     Password for login-based authentication
--transport <type>        Transport type: stdio or sse (default: stdio)
-h, --help                Show help message

配置文件

创建 ~/.config/readur-mcp/config.json 使用任何支持的选项：

{
  "url": "https://readur.example.com",
  "token": "your-jwt-token",
  "transport": "stdio"
}

或者使用用户名/密码凭据：

{
  "url": "https://readur.example.com",
  "username": "admin",
  "password": "your-password",
  "transport": "stdio"
}

如果配置文件不存在，则会自动忽略它。如果文件存在但包含无效的JSON，则会打印警告。

认证

服务器支持两种身份验证模式：

基于令牌的身份验证 --通过以下方式提供预先获得的JWT令牌 --token, READUR_TOKEN，或配置文件。令牌作为承载令牌与每个API请求一起发送。此模式很简单，但需要您在外部管理令牌过期。

基于凭据的身份验证 --通过提供用户名和密码 --username/--password, READUR_USERNAME/READUR_PASSWORD，或配置文件。服务器自动调用 POST /api/auth/login 以获得关于第一API请求的JWT令牌。如果后续请求返回HTTP 401，服务器将透明地重新验证并重试请求一次，因此会话将自动从令牌过期中恢复。

使用AI助手

克劳德代码

使用注册MCP服务器 claude mcp add。您可以通过环境变量或CLI参数提供配置。

使用JWT令牌（环境变量）：

claude mcp add readur-mcp \
  -e READUR_URL=https://readur.example.com \
  -e READUR_TOKEN=your-jwt-token \
  -- node /absolute/path/to/readur-mcp/dist/index.js

使用JWT令牌（CLI参数）：

claude mcp add readur-mcp \
  -- node /absolute/path/to/readur-mcp/dist/index.js \
  --url https://readur.example.com \
  --token your-jwt-token

使用用户名/密码凭据：

claude mcp add readur-mcp \
  -e READUR_URL=https://readur.example.com \
  -e READUR_USERNAME=admin \
  -e READUR_PASSWORD=secret \
  -- node /absolute/path/to/readur-mcp/dist/index.js

要验证服务器是否已注册：

claude mcp list

克劳德桌面版

将服务器添加到您的 claude_desktop_config.json 文件。

使用JWT令牌：

{
  "mcpServers": {
    "readur": {
      "command": "node",
      "args": ["/absolute/path/to/readur-mcp/dist/index.js"],
      "env": {
        "READUR_URL": "https://readur.example.com",
        "READUR_TOKEN": "your-jwt-token"
      }
    }
  }
}

使用用户名/密码凭据：

{
  "mcpServers": {
    "readur": {
      "command": "node",
      "args": ["/absolute/path/to/readur-mcp/dist/index.js"],
      "env": {
        "READUR_URL": "https://readur.example.com",
        "READUR_USERNAME": "admin",
        "READUR_PASSWORD": "your-password"
      }
    }
  }
}

配置文件的位置取决于您的操作系统：

操作系统	路径
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
窗户	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

其他MCP客户端

任何兼容MCP的客户端都可以使用此服务器。服务器通过以下方式进行通信标准默认传输：客户端生成进程并通过stdin/stdout交换JSON-RPC消息。

要与通用MCP客户端集成，请将其配置为：

运行命令： node /absolute/path/to/readur-mcp/dist/index.js
通过环境变量传递配置(READUR_URL, READUR_TOKEN等）或CLI参数(--url, --token等等）
使用stdio传输进行连接

MCP检查员（开发和测试）

MCP Inspector为没有AI客户端的测试工具提供了一个交互式web UI。运行它：

npm run inspector

这将启动 @modelcontextprotocol/inspector 并将其连接到服务器。您可以浏览可用的工具，使用自定义参数调用它们，并检查响应。在运行命令之前设置所需的环境变量，或依赖您的配置文件。

工具参考

文件

工具	说明	参数	模式
`list_documents`	列出具有可选过滤、排序和分页功能的文档。返回ID、标题、MIME类型、状态和文件大小。	`page?` （int）， `pageSize?` （整数，1-100）， `sortBy?` （字符串）， `sortOrder?` （“asc”或“desc”）， `status?` （“待定”、“处理中”、“已完成”、“失败”）， `mimeType?` （字符串）	只读
`get_document`	按ID获取单个文档的完整元数据。返回标题、文件名、MIME类型、状态、页数、文件大小、哈希值和时间戳。	`id` （int）	只读
`get_document_ocr_text`	获取文档的OCR提取文本内容。返回全文和每页文本以及置信度得分。	`id` （int）	只读
`upload_document`	将新文档上传到Readur。支持PDF、TIFF、PNG、JPG和其他图像格式。	`filename` （字符串）， `content` （base64字符串）， `mimeType` （字符串）	正在修改
`delete_document`	按ID永久删除文档。此操作无法撤消。	`id` （int）	破坏性
`retry_document_ocr`	对以前失败或需要重新处理的文档重试OCR处理。	`id` （int）	突变

搜索

工具	说明	参数	模式
`search_documents`	通过文本查询搜索文档，并可选择按MIME类型和状态进行筛选。返回具有相关性得分和文本片段的匹配文档。	`query` （字符串）， `page?` （int）， `pageSize?` （整数，1-100）， `mimeType?` （字符串）， `status?` （“待定”、“正在处理”、“已完成”、“失败”）	只读
`enhanced_search`	使用相关性得分、文本片段和查询建议进行增强搜索，以优化搜索。支持按MIME类型和标签进行筛选。	`query` （字符串）， `page?` （int）， `pageSize?` （整数，1-100）， `mimeType?` （字符串）， `tag?` （字符串）	只读
`get_search_facets`	获取用于筛选的可用搜索方面。返回集合中存在的MIME类型和标记以及文档计数。	（无）	只读

工具	说明	参数	模式
`list_labels`	列出所有可用标签。返回每个标签及其ID、名称、颜色和描述。	（无）	只读
`create_label`	创建可以分配给文档的新标签。	`name` （字符串）， `color?` （字符串，例如“#ff0000”）， `description?` （字符串）	正在修改
`get_document_labels`	获取指定给特定文档的所有标签。	`documentId` （int）	只读
`add_document_label`	为文档分配标签。	`documentId` （int）， `labelId` （int）	突变
`remove_document_label`	从文档中删除标签分配。	`documentId` （int）， `labelId` （int）	破坏性

状态

工具	说明	参数	模式
`whoami`	获取当前已验证用户的ID、用户名、电子邮件和角色。	（无）	只读
`get_settings`	获取当前Readur应用程序设置作为键值对。	（无）	只读
`get_queue_stats`	获取处理队列统计信息：待处理、正在处理、已完成、失败和总作业计数。	（无）	只读
`get_ocr_languages`	获取可用的OCR语言及其代码、名称和安装状态。	（无）	只读

发展

可用脚本

npm run build        # Compile TypeScript to dist/
npm run dev          # Watch mode -- recompiles on file changes
npm run start        # Run the compiled server (dist/index.js)
npm run typecheck    # Type-check without emitting files
npm run inspector    # Launch MCP Inspector for interactive testing

项目结构

readur-mcp/
  package.json
  tsconfig.json
  src/
    index.ts                 # Entry point -- loads config and starts server
    config.ts                # Configuration loading (CLI, env, config file)
    server.ts                # MCP server setup and tool registration
    client/
      readur.ts              # HTTP client for the Readur REST API
    errors/
      index.ts               # Error formatting utilities
    tools/
      index.ts               # Aggregates all tools and handlers
      schemas.ts             # Tool definition helper (defineTool)
      validators.ts          # Shared Zod schemas (pagination, IDs, filters)
      documents.ts           # Document management tools (6 tools)
      search.ts              # Search tools (3 tools)
      labels.ts              # Label management tools (5 tools)
      status.ts              # System status tools (4 tools)
    types/
      api.ts                 # TypeScript type definitions for API responses

故障排除

“错误：需要读取服务器URL” --服务器在任何配置源中都找不到URL。集 READUR_URL 作为环境变量，pass --url 作为CLI参数，或添加 "url" 到您的配置文件。

“错误：需要身份验证” --提供JWT令牌(READUR_TOKEN / --token)或同时输入用户名和密码(READUR_USERNAME + READUR_PASSWORD / --username + --password).

“登录失败”错误 --验证您的用户名和密码是否正确，以及在配置的URL上是否可以访问Readur实例。检查 /api/auth/login 端点是可访问的。

操作过程中出现401个错误 --如果使用基于令牌的身份验证，则令牌可能已过期。获取新令牌并更新配置。如果使用基于凭证的身份验证，服务器会在401个响应上自动重试身份验证；持续的401错误表示凭据无效。

工具未出现在Claude代码中 --快跑 claude mcp list 以确认服务器已注册。如果列出了服务器但缺少工具，请检查服务器日志中的启动错误。确保 dist/ 运行时目录已存在 npm run build.

SSE运输警告 --SSE传输尚未实施。当发生以下情况时，服务器将回退到stdio传输 sse 已配置。使用默认值 stdio 运输。

许可证

麻省理工学院

使用说明

读取MCP服务器

特性

工具摘要

先决条件

安装

配置

环境变量

CLI参数

配置文件

认证

使用AI助手

克劳德代码

克劳德桌面版

其他MCP客户端

MCP检查员（开发和测试）

工具参考

文件

搜索

标签

状态

发展

可用脚本

项目结构

故障排除

许可证

相关 MCP

开源嵌入数据库

文档管理服务

网页内容抓取服务器

知识库存储服务

书签收藏管理工具

文档管理服务器