跳轉到

MCP 伺服器安裝指南

系統需求

需求 最低版本
PHP 8.5+
Composer 2.7+
作業系統 Linux / macOS / Windows（WSL2）
記憶體 256 MB（建議 512 MB+）

安裝套件

# 全域安裝（推薦，讓所有 AI 工具可存取）
composer global require nextpdf/mcp-server

# 或於專案內安裝
composer require nextpdf/mcp-server

驗證安裝

# 全域安裝後
nextpdf-mcp --version
# 輸出：NextPDF MCP Server v1.0.0

# 列出可用工具
nextpdf-mcp list-tools
# 輸出：9 core tools, 0 pro tools (license required), 0 enterprise tools (license required)

解鎖 Pro / Enterprise 工具

# 設定授權金鑰
export NEXTPDF_LICENSE_KEY="your-license-key"
nextpdf-mcp list-tools
# 輸出：9 core tools, 8 pro tools, 8 enterprise tools

Claude Desktop 設定

macOS / Linux

編輯 Claude Desktop 設定檔：

# macOS
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Linux
nano ~/.config/claude/claude_desktop_config.json

添加 NextPDF Connect 伺服器設定：

{
  "mcpServers": {
    "nextpdf": {
      "command": "nextpdf-mcp",
      "args": ["serve"],
      "env": {
        "NEXTPDF_LICENSE_KEY": "your-license-key",
        "NEXTPDF_WORKSPACE": "/path/to/your/pdf/workspace",
        "NEXTPDF_LOG_LEVEL": "warn"
      }
    }
  }
}

Windows（WSL2）

{
  "mcpServers": {
    "nextpdf": {
      "command": "wsl.exe",
      "args": ["-e", "/home/user/.config/composer/vendor/bin/nextpdf-mcp", "serve"],
      "env": {
        "NEXTPDF_LICENSE_KEY": "your-license-key"
      }
    }
  }
}

重啟 Claude Desktop 後，在對話中輸入「使用 NextPDF 解析這份 PDF」即可驗證連線。

VS Code Copilot（MCP Extension）

在 VS Code 設定中添加：

// .vscode/settings.json 或使用者設定
{
  "github.copilot.mcp.servers": {
    "nextpdf": {
      "command": "nextpdf-mcp",
      "args": ["serve"],
      "env": {
        "NEXTPDF_LICENSE_KEY": "${env:NEXTPDF_LICENSE_KEY}",
        "NEXTPDF_WORKSPACE": "${workspaceFolder}"
      }
    }
  }
}

Cursor

在專案根目錄建立 .cursor/mcp.json：

{
  "mcpServers": {
    "nextpdf": {
      "command": "nextpdf-mcp",
      "args": ["serve"],
      "env": {
        "NEXTPDF_LICENSE_KEY": "your-license-key",
        "NEXTPDF_WORKSPACE": "."
      }
    }
  }
}

Windsurf（Codeium）

在 ~/.codeium/windsurf/mcp_config.json 中添加：

{
  "mcpServers": {
    "nextpdf": {
      "serverType": "stdio",
      "command": "nextpdf-mcp",
      "args": ["serve"],
      "env": {
        "NEXTPDF_LICENSE_KEY": "your-license-key"
      }
    }
  }
}

自訂 AI 應用程式整合

使用 stdio 傳輸（推薦）

<?php

declare(strict_types=1);

use NextPDF\MCP\Server;
use NextPDF\MCP\Transport\StdioTransport;

$server = new Server(
    licenseKey: $_ENV['NEXTPDF_LICENSE_KEY'] ?? null,
    workspace: $_ENV['NEXTPDF_WORKSPACE'] ?? getcwd(),
);

$transport = new StdioTransport();
$server->serve($transport);

使用 HTTP 傳輸（服務部署）

use NextPDF\MCP\Transport\HttpTransport;

$server = new Server(
    licenseKey: $_ENV['NEXTPDF_LICENSE_KEY'] ?? null,
);

$transport = new HttpTransport(
    host: '0.0.0.0',
    port: 3000,
    corsOrigins: ['https://my-ai-app.example.com'],
);

$server->serve($transport);

# 啟動 HTTP MCP 服務
NEXTPDF_LICENSE_KEY=your-key php mcp-server.php

LangChain 整合

from langchain_mcp_adapters import MCPToolkit
from langchain import hub

# 連接到 NextPDF MCP 服務
toolkit = MCPToolkit(
    server_url="http://localhost:3000",
    api_key=None  # 依伺服器設定而定
)

tools = toolkit.get_tools()
# tools 包含所有 NextPDF MCP 工具的 LangChain 包裝器

MCP 伺服器設定選項

環境變數 類型 預設值 說明
NEXTPDF_LICENSE_KEY string — Pro/Enterprise 授權金鑰
NEXTPDF_WORKSPACE string cwd PDF 操作的根目錄（安全沙盒）
NEXTPDF_MAX_FILE_SIZE_MB int 100 單一 PDF 最大允許大小（MB）
NEXTPDF_ALLOWED_PATHS string * 允許存取的路徑（逗號分隔，支援 glob）
NEXTPDF_LOG_LEVEL enum warn 日誌等級：error/warn/info/debug
NEXTPDF_TEMP_DIR string 系統 temp 暫存檔案目錄
NEXTPDF_ACCELERATOR_ENDPOINT string — Prisma 加速器端點（Pro/Enterprise）

安全沙盒設定

NEXTPDF_WORKSPACE 定義了 MCP 工具能存取的根目錄。工具不能存取此目錄以外的路徑，防止路徑穿越攻擊：

# 只允許存取 /app/documents 目錄內的 PDF
NEXTPDF_WORKSPACE=/app/documents nextpdf-mcp serve

診斷與疑難排解

# 診斷模式（詳細輸出）
NEXTPDF_LOG_LEVEL=debug nextpdf-mcp serve --dry-run

# 測試單一工具
nextpdf-mcp call parse_pdf '{"path": "/tmp/test.pdf"}'

# 驗證授權金鑰
nextpdf-mcp verify-license

# 檢查 PHP 相依套件
nextpdf-mcp check-deps

常見問題

Q：Claude Desktop 找不到 nextpdf-mcp 命令

# 確認全域 Composer bin 在 PATH 中
echo $PATH | grep composer
# 若無，添加至 ~/.bashrc 或 ~/.zshrc：
export PATH="$PATH:$HOME/.config/composer/vendor/bin"

Q：Pro/Enterprise 工具顯示 "License required"

確認 NEXTPDF_LICENSE_KEY 環境變數已在 MCP 設定的 env 區段中設定，而非僅在 shell 中設定。Claude Desktop 等 GUI 應用程式不繼承 shell 環境變數。

參見