Stirling Pdf

MCP文档知识

提供方 gufao

文档知识 stdio · 本地进程 API Key 社区 / 第三方 Claude DesktopClaude
查看接入方式

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

一句话选型结论

按资料字段整理

Stirling Pdf 属于文档知识类 MCP 服务器,stdio · 本地进程,API Key,可直接接入 Claude Desktop、Claude,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类文档知识 传输方式stdio · 本地进程 鉴权API Key 部署方式本地部署
GitHub 星标 1 仓库热度,无公开仓库时显示未标注
工具数 10 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

文档知识
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量10暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

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

安装与配置

stdio · 本地进程 API Key
客户端在本机拉起子进程,数据不出本机
docker run -d \

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Docker,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 10 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
文档检索问答

在你的文档库里按问题找答案。

知识库读写

把新资料写进知识库,随用随取。

内容整理

把零散资料归纳成结构化笔记。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 10 个工具,职责相对集中,接入后不容易误操作。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好API Key对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在文档知识场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Stirling Pdf当前 10 stdio · 本地进程 本地部署 有 2026-05-17
dify 未标注 stdio · 本地进程 本地部署 有 2026-04-11
open-webui 未标注 stdio · 本地进程 本地部署 有 2026-04-11
JeecgBoot 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Cherry Studio 未标注 未标注 未标注 无 2026-05-17
mempalace 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

文档知识
字段来自项目仓库与公开索引,中文说明由本站标注
提供方gufao上游标注的维护方 gufao
分类文档知识本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式API Key远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Docker本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

13.1 KB
来自项目仓库与上游目录的原文,未做删改

斯特林PDF MCP服务器

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

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

最新动态

v1.1.0版本 -2025年12月

  • ✅ 修复了多部分/表单数据处理问题 -从本地切换 fetch 到 axios 用于从Docker容器可靠地上传文件
  • ✅ 固定水印功能 -通过确保解决“colorString为null”错误 customColor 参数已正确发送
  • ✅ 改进了错误处理 -现在显示来自Stirling PDF API的实际错误消息
  • ✅ 已验证Docker MCP网关兼容性 -使用Docker桌面MCP工具包进行全面测试

目的

此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服务器。选项:

  1. Docker(推荐):```bash
    docker run -d \
    -p 8080:8080 \
    -v ./configs:/configs \
    -v ./logs:/logs \
    -e DOCKER_ENABLE_SECURITY=false \
    --name stirling-pdf \
    frooodle/s-pdf:latest

1. **Docker Compose**:参见 官方文档

1. **自托管**:遵循 安装指南

## 安装

### 第一步:保存文件```bash
# Project files are already in the repository
cd mcp-server-stirling-pdf

步骤2:安装依赖项```bash

npm install


**关键依赖关系**:

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

### 步骤3:构建TypeScript```bash
npm run build

步骤4:构建Docker镜像```bash

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


### 第五步:设置秘密```bash
# 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:创建自定义目录```bash

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:```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:更新注册表```bash

Edit registry file

nano ~/.docker/mcp/registry.yaml


在现有条目下添加此条目 `registry:` 按键:```yaml
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数组中:```json
{
"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:重新启动克劳德桌面

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

### 步骤10:测试您的服务器```bash
# 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 <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"tools/list"}
EOF

# You should see a JSON response listing all 10 tools

# Check logs if needed
docker ps
docker logs

在Claude Desktop中进行测试:重新启动Claude后,问:

  • “你们有什么PDF工具?”
  • “在此PDF中添加一个标有“测试”的水印”(上传PDF文件)

发展

本地开发```bash

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


### 本地测试```bash
# 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交互

添加新工具

  1. 在中定义工具功能 src/index.ts:```typescript
    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。

2. 将工具定义添加到 `TOOLS` 数组:```typescript
{
name: "my_new_tool",
description: "What it does",
inputSchema: {
type: "object",
properties: {
param: { type: "string", description: "Description" }
},
required: ["param"]
}
}
  1. 将案例添加到工具处理程序:```typescript
    case "my_new_tool": {
    const param = (args?.param as string) || "";
    return {
    content: [{ type: "text", text: await myNewTool(param) }]
    };
    }

4. 重建和重新部署:```bash
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服务器外部工作:bash 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/

来源

  • Stirling PDF API文档
  • Stirling PDF GitHub仓库
  • Stirling PDF入门指南
  • 关于DeepWiki的API参考

许可证

GPL-3.0

贡献

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

由18X实验室建造

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

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Stirling Pdf 怎么安装?

在客户端按下面的安装命令接入:docker run -d \。装完在客户端配置里引用同一个包或端点。

Stirling Pdf 怎么在 Claude Desktop、Claude 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Stirling Pdf 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Stirling Pdf 需要 API Key 吗?

资料标注需要API Key认证,使用前准备好对应凭据,并按最小权限配置。

Stirling Pdf 支持哪些客户端?

资料标注支持 Claude Desktop、Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Stirling Pdf 能提供哪些能力?

资料显示约 10 个工具;能力标签包括 PDF处理、文档转换、JavaScript、Claude。具体工具清单以官方文档为准。

Stirling Pdf 需要什么运行环境?

运行时为 Docker;属于本地进程,需要在本机装好运行环境。

Stirling Pdf 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。