快速接入

先看主来源和安装命令，再打开仓库或文档；下面只保留这个条目的关键接入事实。

命令预览

docker run -d \

详细介绍

斯特林PDF MCP服务器

模型上下文协议（MCP）服务器，提供与Stirling PDF的安全集成，使AI助手能够执行全面的PDF操作。

使用TypeScript构建，用于类型安全和现代开发实践。

目的

此MCP服务器为AI助手提供了一个安全的接口，使其能够与自托管的Stirling PDF实例进行交互，从而直接从Claude Desktop或其他MCP兼容客户端实现强大的PDF操作功能。

特性

当前实施情况

merge_pdfs -将多个PDF文件合并到一个文档中
split_pdf -按指定页码将PDF拆分为多个文件
compress_pdf -通过可配置的优化级别压缩PDF文件以减小大小
convert_pdf_to_images -将PDF页面转换为图像文件（PNG、JPG、GIF）
rotate_pdf -在PDF文档中旋转页面
add_watermark -为PDF文档添加文本水印
remove_pages -从PDF中删除指定页面
extract_images -从PDF文档中提取所有图像
convert_images_to_pdf -将一个或多个图像转换为PDF文档
ocr_pdf -对PDF执行OCR以使其可搜索

先决条件

Node.js 20或更高版本
启用MCP工具包的Docker桌面
Docker MCP CLI插件 (docker mcp 命令）
Stirling PDF实例 -正在运行的Stirling PDF服务器（自托管或可访问）

- 下载地址：https://github.com/Stirling-Tools/Stirling-PDF - Docker快速入门： docker run -d -p 8080:8080 frooodle/s-pdf:latest

获取您的Stirling PDF实例

您需要一个正在运行的Stirling PDF实例来使用此MCP服务器。选项：

Docker（推荐）:

   docker run -d \
     -p 8080:8080 \
     -v ./configs:/configs \
     -v ./logs:/logs \
     -e DOCKER_ENABLE_SECURITY=false \
     --name stirling-pdf \
     frooodle/s-pdf:latest

Docker Compose：参见官方文档

自托管：遵循安装指南

安装

第一步：保存文件

# Project files are already in the repository
cd mcp-server-stirling-pdf

步骤2：安装依赖项

npm install

关键依赖关系:

@modelcontextprotocol/sdk -MCP协议实现
axios -用于可靠多部分/表单数据上传的HTTP客户端
form-data -多部分表单数据库
typescript -类型安全开发

步骤3：构建TypeScript

npm run build

步骤4：构建Docker镜像

docker build -t stirling-pdf-mcp-server .

第五步：设置秘密

# Set your Stirling PDF instance URL
docker mcp secret set STIRLING_PDF_URL="http://host.docker.internal:8080"

# If your Stirling PDF has authentication enabled, set the API key
docker mcp secret set STIRLING_PDF_API_KEY="your-api-key-here"

# Verify secrets
docker mcp secret list

备注：使用 http://host.docker.internal:8080 连接到主机上运行的Stirling PDF。

步骤6：创建自定义目录

# Create catalogs directory if it doesn't exist
mkdir -p ~/.docker/mcp/catalogs

# Create or edit custom.yaml
nano ~/.docker/mcp/catalogs/custom.yaml

将此条目添加到custom.yaml：

version: 2
name: custom
displayName: Custom MCP Servers
registry:
  stirling-pdf:
    description: "MCP server for Stirling PDF - comprehensive PDF manipulation capabilities"
    title: "Stirling PDF"
    type: server
    dateAdded: "2025-12-17T00:00:00Z"
    image: stirling-pdf-mcp-server:latest
    ref: ""
    readme: ""
    toolsUrl: ""
    source: ""
    upstream: ""
    icon: ""
    tools:
      - name: merge_pdfs
      - name: split_pdf
      - name: compress_pdf
      - name: convert_pdf_to_images
      - name: rotate_pdf
      - name: add_watermark
      - name: remove_pages
      - name: extract_images
      - name: convert_images_to_pdf
      - name: ocr_pdf
    secrets:
      - name: STIRLING_PDF_URL
        env: STIRLING_PDF_URL
        example: "http://host.docker.internal:8080"
      - name: STIRLING_PDF_API_KEY
        env: STIRLING_PDF_API_KEY
        example: "your-api-key-here"
    metadata:
      category: productivity
      tags:
        - pdf
        - documents
        - conversion
        - ocr
      license: GPL-3.0
      owner: local

步骤7：更新注册表

# Edit registry file
nano ~/.docker/mcp/registry.yaml

在现有条目下添加此条目 registry: 按键：

registry:
  # ... existing servers ...
  stirling-pdf:
    ref: ""

重要：条目必须在 registry: 密钥，而不是根级别。

步骤8：配置Claude桌面

查找您的Claude Desktop配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

编辑文件并将自定义目录添加到args数组中：

{
  "mcpServers": {
    "mcp-toolkit-gateway": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "-v", "/Users/your_username/.docker/mcp:/mcp",
        "docker/mcp-gateway",
        "--catalog=/mcp/catalogs/docker-mcp.yaml",
        "--catalog=/mcp/catalogs/custom.yaml",
        "--config=/mcp/config.yaml",
        "--registry=/mcp/registry.yaml",
        "--tools-config=/mcp/tools.yaml",
        "--transport=stdio"
      ]
    }
  }
}

替换 /Users/your_username 使用您的实际主目录路径：

macOS: /Users/your_username
视窗: C:\\Users\\your_username （使用双反睫毛）
Linux: /home/your_username

步骤9：重新启动克劳德桌面

完全退出克劳德桌面
重新启动克劳德桌面
您的Stirling PDF工具现在应该出现了！

步骤10：测试您的服务器

# Verify it appears in the list
docker mcp server list | grep stirling

# Test the server manually (optional)
docker run --rm -i \
  -e STIRLING_PDF_URL=http://host.docker.internal:8080 \
  -e STIRLING_PDF_API_KEY=your-api-key \
  stirling-pdf-mcp-server:latest \
  node /app/dist/index.js

在Claude Desktop中进行测试：重新启动Claude后，问：

“你们有什么PDF工具？”
“在此PDF中添加一个标有“测试”的水印”（上传PDF文件）

发展

本地开发

# Install dependencies
npm install

# Run in development mode with auto-reload
npm run dev

# Type check
npm run typecheck

# Build
npm run build

# Run production build
npm start

本地测试

# Set environment variables for testing
export STIRLING_PDF_URL="http://localhost:8080"
export STIRLING_PDF_API_KEY="test-key"

# Run directly
npm start

使用示例

在Claude Desktop中，您可以问：

合并PDF

“将这两个PDF文件合并为一个”
“合并我刚刚发送给您的所有PDF文档”

拆分PDF

“将此PDF拆分为第3页和第7页”
“在第5页将此PDF拆分为单独的文件”

压缩PDF

“压缩此PDF使其更小”
“使用高压缩率减小此PDF的文件大小”

转换PDF

“将此PDF转换为300 DPI的PNG图像”
“将这些图像转换为单个PDF”

旋转PDF

“将此PDF中的所有页面旋转90度”
将第2、3和4页旋转180度

水印

“在此PDF中添加“草稿”水印”
“添加‘机密’作为水印，不透明度为30%”

页面操作

从此PDF中删除第1、3和5页
“提取此PDF中的所有图像”

光学字符识别

“使用OCR使此扫描的PDF可搜索”
“用英语和西班牙语对此PDF执行OCR”

建筑

Claude Desktop → MCP Gateway → Stirling PDF MCP Server → Stirling PDF Instance
                       ↓
            Docker Desktop Secrets
              (URL, API Key)

技术栈

语言：TypeScript（严格模式）
HTTP客户端：Axios（用于可靠的多部分/表单数据处理）
MCP-SDK：@modelcontextprotocol/sdk
运输：stdio（标准输入/输出）
表单数据：用于多部分上传的表单数据库
运行时：Node.js 20+

文件格式

所有PDF和图像文件都以 base64数据URL.Claude Desktop会在您上传文件时自动处理此问题。

示例格式：

data:application/pdf;base64,JVBERi0xLjQKJeLjz9MKM...

TypeScript的好处

类型安全：在编译时捕获错误
更好的IDE支持：增强的自动补全和重构
现代JavaScript：使用最新的ECMAScript功能
可维护性：具有类型的自文档化代码
API类型定义：强类型Stirling PDF API交互

添加新工具

在中定义工具功能 src/index.ts:

async function myNewTool(param: string): Promise {
  try {
    validateRequired(param, "param");

    const formData = new FormData();
    const buffer = base64ToBuffer(param); // Convert base64 data URL to Buffer
    formData.append("fileInput", buffer, "input.pdf");
    // Add additional parameters as needed
    formData.append("paramName", "paramValue");

    const resultBuffer = await callStirlingAPI("/api/v1/endpoint", formData);
    const resultBase64 = bufferToBase64DataUrl(resultBuffer);

    return `✅ Success message\n\n📄 Result:\n${resultBase64}`;
  } catch (error) {
    logger.error("Error:", error);
    return formatError(error);
  }
}

备注：The callStirlingAPI 函数使用axios进行可靠的多部分/表单数据处理。所有文件上传必须使用 Buffer 对象，而不是浏览器中的原始FormData。

将工具定义添加到 TOOLS 数组：

{
  name: "my_new_tool",
  description: "What it does",
  inputSchema: {
    type: "object",
    properties: {
      param: { type: "string", description: "Description" }
    },
    required: ["param"]
  }
}

将案例添加到工具处理程序：

case "my_new_tool": {
  const param = (args?.param as string) || "";
  return {
    content: [{ type: "text", text: await myNewTool(param) }]
  };
}

重建和重新部署：

npm run build
docker build -t stirling-pdf-mcp-server .

故障排除

工具未出现

验证Docker镜像构建成功： docker images | grep stirling-pdf
检查目录文件语法： cat ~/.docker/mcp/catalogs/custom.yaml
确保Claude Desktop配置包括自定义目录
完全重新启动克劳德桌面

连接错误

验证Stirling PDF是否正在运行： curl http://localhost:8080
检查是否在secrets中使用了正确的URL： docker mcp secret list
使用 host.docker.internal 而不是 localhost 用于基于主机的Stirling PDF
检查防火墙设置

身份验证错误

验证是否设置了机密： docker mcp secret list
检查Stirling PDF是否启用了安全功能
验证API密钥在Stirling PDF设置中是否正确
使用卷曲测试API键： curl -H "X-API-KEY: your-key" http://localhost:8080/api/v1/info/status

构建错误

检查TypeScript版本兼容性： npm run typecheck
确保安装了所有依赖项： npm install
清除node_modules并重新安装： rm -rf node_modules && npm install

PDF操作失败

检查Stirling PDF配置中的文件大小限制
验证PDF文件是否有效且未损坏
查看Stirling PDF日志： docker logs stirling-pdf
确保超时时间足以容纳大文件（默认值：2分钟）

水印错误（colorString为空）

如果你看到 Cannot invoke "String.startsWith(String)" because "colorString" is null:

当 customColor 参数缺失或格式不正确
MCP服务器自动包括 customColor=#000000 （黑色水印）
在最新版本中，通过使用axios而不是fetch修复了这个问题
如果您修改了代码，请确保 customColor 参数包含在水印请求中

Stirling PDF中的HTTP 400/500错误

确认您正在使用axios：原生Node.js fetch API存在Docker容器中的多部分/表单数据问题
检查参数格式：Stirling PDF对参数格式敏感
查看Stirling PDF日志: docker logs stirling-pdf --tail 50 显示了实际的Java错误
卷曲测试：验证API在MCP服务器外部工作：

  curl -X POST http://localhost:8080/api/v1/security/add-watermark \
    -H "X-API-KEY: your-key" \
    -F "fileInput=@test.pdf" \
    -F "watermarkType=text" \
    -F "watermarkText=TEST" \
    -F "customColor=#000000"

安全注意事项

存储在Docker Desktop secrets中的所有秘密（从未硬编码）
API密钥通过X-API-key头安全传输
在Docker容器中以非root用户身份运行
从未记录敏感数据
所有参数的输入验证
外部呼叫超时保护（2分钟超时）
Stirling PDF在本地运行-没有数据发送到外部服务

斯特林PDF API参考

有关完整的Stirling PDF API文档，请访问：

您的实例： http://your-instance:port/swagger-ui/index.html
官方文件：https://docs.stirlingpdf.com/API/

来源

许可证

GPL-3.0

贡献

该项目遵循GPL-3.0许可证。所有修改必须符合GPL-3.0要求。

由18X实验室建造

赋予AI助手全面的PDF操作能力。

目录标签

PDF处理文档转换JavaScriptClaude本地部署OCR文件管理AI集成

支持客户端

Claude DesktopClaude

接入字段

传输方式（transport，传输协议）

stdio

鉴权方式（authType，认证方式）

api-key

运行时（runtime，运行环境）

Docker

工具数量（toolCount，工具数）

10

资源数量（resourceCount，资源数）

0

提示词数量（promptCount，提示词数）

0

权限和风险

stdioapi-key部署方式未说明

接入前请确认传输方式、认证方式和部署位置，并根据实际工具能力限制访问范围。

安装前确认

不要直接授予不必要的文件、网络或账号权限；先核对安装命令和配置内容。

来源信息

MCP World

mcpworld.com

/detail/8ccf2d51b77d3bfb552559d159993123

一个提供PDF文件合并、拆分、压缩、转换等操作的MCP服务器，适用于AI助手进行PDF文档处理。

继续浏览同类 MCP

更多文档知识 MCP（3,282）返回 MCP 目录

上一个 MCP

Stickyrice MCP

Stickyrice-MCP是一个用于与Claude笔记交互的模型上下文协议服务器，提供工作区、看板、标签等笔记管理功能。

下一个 MCP

Stormbreaker06 MCP

一个简单的笔记存储系统，支持自定义URI方案访问笔记，提供笔记摘要生成和添加新笔记的功能。

Stirling Pdf