Readur MCP

读取MCP服务器

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

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

特性

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

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

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

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

工具摘要

先决条件

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

安装

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

git clone 
cd readur-mcp
npm install
npm run build

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

配置

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

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

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

环境变量

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

CLI参数

--url                Readur server URL (required, no trailing slash)
--token            Pre-obtained JWT authentication token
--username      Username for login-based authentication
--password 
     Password for login-based authentication
--transport         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"
      }
    }
  }
}

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

其他MCP客户端

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

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

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

MCP检查员（开发和测试）

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

npm run inspector

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

工具参考

文件

搜索

标签

状态

发展

可用脚本

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 运输。

许可证

麻省理工学院