SignNow MCP Server

关于 SignNow API

SignNow REST API 可为签署者、准备者和发送者提供流畅的电子签名体验。预填文档、创建供多位签署者使用的嵌入式品牌工作流、请求付款，并实时跟踪签名状态。确保在任何设备上都能轻松、安全、直观地完成签署。

使用 SignNow API 可以完成的操作：

• 按基于角色的顺序发送文档和文档组以供签署
• 根据文档创建可重复使用的模板
• 使用数据预填文档字段
• 在签署流程中收取付款
• 将文档发送、签署或编辑体验嵌入到您的网站、应用程序或任何记录系统中
• 跟踪签署进度并下载已完成的文档

---

SignNow MCP 服务

一个模型上下文协议（MCP）服务，让 AI Agent 能通过 STDIO 或 Streamable HTTP 安全、结构化地访问 SignNow 电子签名工作流——包括模板、嵌入式签署、邀请、状态跟踪和文档下载。

mcp-name: io.github.signnow/sn-mcp-server

---

目录

• 功能

• 快速开始

  • 前提条件
  • 快速运行（uvx）
  • 1. 设置环境变量
  • 2. 安装并运行
  • 本地/远程（HTTP）
  • Docker
  • Docker Compose

• 配置

  • 身份验证选项
  • SignNow 和 OAuth 设置
  • 生产环境密钥管理

• 客户端设置

  • VS Code — GitHub Copilot（Agent 模式）/ Cursor
  • Claude Desktop
  • Glama（托管的 MCP）
  • MCP Inspector（测试）

• 工具

• 常见问题/提示

• 示例

• 实用资源

  • 示例应用
  • API 文档
  • SignNow API Helper MCP

• 许可证

---

功能

• 模板和文档组

  • 浏览所有模板和模板组
  • 根据模板创建文档或文档组（包括一次性工作流）

• 邀请和嵌入式用户体验

  • 电子邮件邀请和有序的收件人
  • 用于应用内体验的嵌入式签署/发送/编辑链接

• 状态和获取

  • 检查邀请状态和步骤详情
  • 下载最终文档（单个或合并）
  • 读取规范化的文档/文档组结构，以便进行程序化决策

• 传输方式

  • STDIO（最适合本地客户端）
  • Streamable HTTP（最适合 Docker/远程场景）

---

快速开始

前提条件

• SignNow 账户。创建免费开发者账户。
• SignNow 凭据：您需要账户电子邮件、密码和应用程序 Basic Authorization Token。入门指南。
• 一个已启用的 SignNow API 应用程序。
• 系统已安装 Python 3.11+（使用 python3 --version 检查）
• 已安装 UVX（使用 uvx --version 检查）。建议使用此方式快速完成设置。
• 已配置环境变量
• 如果您的客户端支持 Streamable HTTP，可以使用预先部署的服务 URL https://mcp-server.signnow.com/mcp，而无需在本地运行。

快速运行（uvx）

如果您使用 uv，可以不安装软件包直接运行服务：

uvx --from signnow-mcp-server sn-mcp serve

1. 设置环境变量

# Create .env file with your SignNow credentials
# You can copy from env.example if you have the source code
# Or create .env file manually with required variables (see Environment Variables section below)

2. 安装并运行

选项 A：从 PyPI 安装（推荐）

# Install the package from PyPI
pip install signnow-mcp-server

# Run MCP server in standalone mode
sn-mcp serve

选项 B：从源代码安装（开发）

# 1) Clone & configure
git clone https://github.com/signnow/sn-mcp-server.git
cd sn-mcp-server
cp .env.example .env
# fill in your values in .env

# 2) Install (editable for dev)
pip install -e .

# 3) Run as STDIO MCP server (recommended for local tools & Inspector)
sn-mcp serve

STDIO 非常适合桌面客户端和本地测试。

本地/远程（HTTP）

# Start HTTP server on 127.0.0.1:8000
sn-mcp http

# Custom host/port
sn-mcp http --host 0.0.0.0 --port 8000

# Dev reload
sn-mcp http --reload

默认情况下，Streamable HTTP MCP 端点在 /mcp 下提供服务。示例 URL：

http://localhost:8000/mcp

Docker

# Build
docker build -t sn-mcp-server .

# Run HTTP mode (recommended for containers)
docker run --env-file .env -p 8000:8000 sn-mcp-server sn-mcp http --host 0.0.0.0 --port 8000

在容器中使用 STDIO 时，许多客户端的连接都不可靠。使用 Docker 时，建议优先使用 HTTP。

Docker Compose

# Only the MCP server
docker-compose up sn-mcp-server

# Both services (if defined)
docker-compose up

---

配置

将 .env.example 复制为 .env 并填写相应值。启动时，所有设置都会通过 pydantic-settings 验证。

身份验证选项

1) API 密钥 / 访问令牌（最简单）

SIGNNOW_ACCESS_TOKEN=<your_api_key>
# or equivalently:
SIGNNOW_API_KEY=<your_api_key>

生成 API 密钥 →

2) 用户名 / 密码

SIGNNOW_USER_EMAIL=<email>
SIGNNOW_PASSWORD=<password>
SIGNNOW_API_BASIC_TOKEN=<base64 basic token>

3) OAuth 2.0（适用于托管/高级场景）

SIGNNOW_CLIENT_ID=<client_id>
SIGNNOW_CLIENT_SECRET=<client_secret>
# + OAuth server & RSA settings below

使用某些桌面客户端运行时，可能仅支持用户名/密码。

每次请求的访问令牌（HTTP 传输）

对于多租户/代理部署，封装后端可以通过专用 HTTP 标头，在每次请求中附加原始 SignNow 访问令牌——无需环境配置，也不会复用承载 MCP/OAuth bearer 的 Authorization：

X-SignNow-Access-Token: <raw SignNow access_token>

• 值为原始令牌——不带 Bearer 前缀。
• 按每次请求解析；不会缓存或存储任何内容（无状态）。
• 优先级：环境中配置的 SIGNNOW_ACCESS_TOKEN（选项 1）仍然优先。若要将 标头用作真正的逐请求凭据，请不要同时设置 SIGNNOW_ACCESS_TOKEN， 否则每个请求都会使用环境变量中的令牌。该标头的优先级高于通用的 Authorization: Bearer。
• 仅适用于 HTTP 传输（sn-mcp http）。它不会作为工具参数公开，因此令牌永远不会进入模型的上下文或对话日志。请通过 HTTPS 发送。

SignNow 和 OAuth 设置

# SignNow endpoints (defaults shown)
SIGNNOW_APP_BASE=https://app.signnow.com
SIGNNOW_API_BASE=https://api.signnow.com

# OAuth server (if you enable OAuth mode)
OAUTH_ISSUER=<your_issuer_url>
ACCESS_TTL=3600
REFRESH_TTL=2592000
ALLOWED_REDIRECTS=<comma,separated,uris>

# RSA keys for OAuth (critical in production)
OAUTH_RSA_PRIVATE_PEM=<PEM content>
OAUTH_JWK_KID=<key id>

生产环境密钥管理

如果生产环境中缺少 OAUTH_RSA_PRIVATE_PEM，每次重启都会生成新的 RSA 密钥，导致所有现有令牌失效。在生产环境中，务必通过密钥管理提供持久的私钥。

---

客户端设置

VS Code — GitHub Copilot（Agent 模式）/ Cursor

在工作区中创建 .vscode/mcp.json / .cursor/mcp.json：

STDIO（本地）：

{
  "servers": {
    "signnow": {
      "command": "sn-mcp",
      "args": ["serve"],
      "env": {
        "SIGNNOW_USER_EMAIL": "${env:SIGNNOW_USER_EMAIL}",
        "SIGNNOW_PASSWORD": "${env:SIGNNOW_PASSWORD}",
        "SIGNNOW_API_BASIC_TOKEN": "${env:SIGNNOW_API_BASIC_TOKEN}"
      }
    }
  }
}

STDIO（uvx — 无需本地安装）：

{
  "servers": {
    "signnow": {
      "command": "uvx",
      "args": ["--from", "signnow-mcp-server", "sn-mcp", "serve"],
      "env": {
        "SIGNNOW_USER_EMAIL": "${env:SIGNNOW_USER_EMAIL}",
        "SIGNNOW_PASSWORD": "${env:SIGNNOW_PASSWORD}",
        "SIGNNOW_API_BASIC_TOKEN": "${env:SIGNNOW_API_BASIC_TOKEN}"
      }
    }
  }
}

HTTP（远程或 Docker）：

{
  "servers": {
    "signnow": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

然后打开 Chat → Agent 模式，启用 signnow 工具，并在提示词中使用它们。

注意：Cursor 使用相同的配置——在 MCP 设置（STDIO 或 HTTP）下添加即可。对于 STDIO，也可以使用上文所示的 uvx。

Claude Desktop

使用 Desktop Extensions 或手动配置 MCP（Developer → Edit config）。

步骤：

1. 打开 Claude Desktop → Developer → Edit config
2. 在 mcpServers 下添加新的服务条目
3. 保存并重启 Claude Desktop

示例：

STDIO（本地安装）：

{
  "mcpServers": {
    "signnow": {
      "command": "sn-mcp",
      "args": ["serve"],
      "env": {
        "SIGNNOW_USER_EMAIL": "${env:SIGNNOW_USER_EMAIL}",
        "SIGNNOW_PASSWORD": "${env:SIGNNOW_PASSWORD}",
        "SIGNNOW_API_BASIC_TOKEN": "${env:SIGNNOW_API_BASIC_TOKEN}"
      }
    }
  }
}

STDIO（uvx — 无需本地安装）：

{
  "mcpServers": {
    "signnow": {
      "command": "uvx",
      "args": ["--from", "signnow-mcp-server", "sn-mcp", "serve"],
      "env": {
        "SIGNNOW_USER_EMAIL": "${env:SIGNNOW_USER_EMAIL}",
        "SIGNNOW_PASSWORD": "${env:SIGNNOW_PASSWORD}",
        "SIGNNOW_API_BASIC_TOKEN": "${env:SIGNNOW_API_BASIC_TOKEN}"
      }
    }
  }
}

HTTP（远程或 Docker）：

{
  "mcpServers": {
    "signnow": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

然后在 Claude 的聊天中启用该服务并开始使用工具。

Glama（托管 MCP）

只需简单设置，即可在 Glama 上部署并运行此服务：

步骤：

1. 打开 Glama 上的服务页面：Glama 上的 sn-mcp-server
2. 点击红色的“Deploy Server”按钮
3. 在环境变量中填写：
   • SIGNNOW_USER_EMAIL
   • SIGNNOW_PASSWORD
   • SIGNNOW_API_BASIC_TOKEN
   • （其他变量可保留默认值）
4. 在 Glama 中创建访问令牌并复制端点 URL。格式如下：

https://glama.ai/endpoints/{someId}/mcp?token={glama-mcp-token}

在任何支持 HTTP 传输的客户端中使用此 HTTP MCP URL（例如 VS Code/Cursor JSON 配置或上文 Claude Desktop 的 HTTP 示例）。

MCP Inspector（测试）

非常适合通过可视化界面探索工具和架构。

# Start Inspector (opens UI on localhost)
npx @modelcontextprotocol/inspector

# Connect (STDIO): run your server locally and attach
sn-mcp serve

# Or connect (HTTP): use http://localhost:8000/mcp

你可以列出工具、使用 JSON 参数调用它们，并检查响应。

---

工具

每个工具都有简要说明；使用 MCP 客户端（例如 Inspector）查看确切的 JSON 架构。

• list_all_templates — 列出模板和模板组，并显示简化的元数据。支持使用 limit/offset 分页（默认每页 50 项）。
• list_contacts — 按姓名、电子邮件或电话号码搜索 CRM 联系人。返回 ID、电子邮件、名和姓，以及公司。在使用 send_invite 之前，先按姓名查找收件人的电子邮件地址。支持 per_page（默认 15，最多 100）。
• list_documents — 浏览文档、文档组和状态。支持使用 limit/offset 分页（默认每页 50 项）。
• create_from_template — 根据模板或模板组创建文档或文档组。
• create_template — 将文档或文档组转换为可重复使用的签署模板。
• send_invite — 发送电子邮件邀请（文档或文档组），支持按顺序指定收件人。自动检测自由格式文档（没有字段）——对于自由格式收件人，请省略 role。设置 self_sign=True（且不设置 orders）即可自行签署文档：该工具会在服务器端解析您的电子邮件，并返回一个 SendInviteResponse，其中可选的 link 字段包含可直接打开的签署链接（自由格式收件人的电子邮件与已验证用户匹配时，也会填充此字段）。如果是模板或模板组，该工具会先自动创建文档或文档组。
• create_embedded_invite — 为文档、文档组或模板创建嵌入式签署会话，不发送电子邮件。如果是模板或模板组，该工具会先自动创建文档或文档组。
• create_embedded_sending — 为文档、文档组或模板创建嵌入式“发送/管理”体验。如果是模板或模板组，该工具会先自动创建文档或文档组。
• create_embedded_editor — 为文档、文档组或模板生成嵌入式编辑器链接，以放置或调整字段。如果是模板或模板组，该工具会先自动创建文档或文档组。
• send_invite_from_template — 一步完成：根据模板创建文档并发送邀请。
• create_embedded_sending_from_template — 一步完成：模板 → 嵌入式发送。
• create_embedded_editor_from_template — 一步完成：模板 → 嵌入式编辑器。
• create_embedded_invite_from_template — 一步完成：模板 → 嵌入式签署。
• get_invite_status — 获取文档或文档组当前的邀请状态和步骤。涵盖字段邀请和自由格式邀请（两者同时存在时优先采用字段流程）。响应包含 invite_mode（field 或 freeform）。对于自由格式文档组，签署人电子邮件来自组的 documents 列表（signature_requests）。
• get_document_download_link — 获取直接下载链接（文档组返回合并后的输出）。
• get_signing_link — 获取文档或文档组的签署链接。
• get_document — 获取经过规范化的文档/文档组结构及字段值；在 v3.0 中还会返回实体所在的文件夹（folder_id/folder_name）。
• update_document_fields — 预填单个文档中的文本字段。
• upload_document — 从本地文件路径（file_path）、公开 URL（file_url）或 MCP 资源附件（resource_uri）上传文件。设置 kind='template'（默认值为 'document'），即可将文件保存为可重复使用的模板，而非普通文档（此时返回的 document_id 是模板 ID，next_steps 也会切换为模板后续步骤）。对于 file_path，解析后的路径必须位于配置的安全基目录内（默认为用户的主目录）；基目录之外的路径无法通过验证。支持的格式：PDF、DOC、DOCX、PNG、JPG、JPEG。最大 40 MB。返回 document_id、filename、source。
• send_invite_reminder — 向文档或文档组中尚未签署的签署人发送签署提醒。
• cancel_invite — 取消文档或文档组中所有有效（待处理）的签署邀请。自动检测实体类型和邀请类型（字段或自由格式）。返回状态：cancelled（已取消）、completed（已完成）或 invite_not_sent（尚未发送邀请）。
• update_invite_recipient — 替换待处理字段邀请的签署收件人。查找当前签署人的待处理邀请，并替换为新的电子邮件地址。支持文档和文档组。仅支持字段邀请——不支持自由格式邀请或嵌入式邀请。
• view_document — 为文档或文档组生成只读嵌入式查看链接。在兼容 MCP Apps 的客户端中，文档会内嵌显示；在其他宿主中，则会返回可点击的 URL。
• rename_entity — 重命名文档、文档组、模板或模板组。未指定实体类型时会自动检测。
• signnow_skills — 查询随附的 SignNow 技能库。省略 skill_name 可列出所有可用技能及其说明；提供 skill_name（例如 signnow101）可获取完整的 Markdown 正文。使用 signnow101 了解 SignNow 实体类型、邀请类型和工具映射。
  • 列表模式示例：{"skills": [{"name": "signnow101", "description": "SignNow 101 概念参考……（为简洁起见，省略部分说明）"}]}
  • 获取模式示例：{"name": "signnow101", "body": "# SignNow 101 — 概念参考\n..."}

提示：先运行 signnow_skills（不带参数）以发现可用技能，然后依次运行 list_all_templates → create_from_template → create_embedded_* / send_invite，接着运行 get_invite_status 和 get_document_download_link。

---

常见问题 / 提示

• STDIO 还是 Docker？ 本地开发时优先使用 STDIO；在 Docker 中使用 HTTP。
• 沙盒还是生产环境？ 从 SignNow 的沙盒 / 开发凭据开始；生产环境需要正确配置 OAuth 和持久化 RSA 私钥。
• 在哪里查看准确的工具架构？ 使用 MCP Inspector 或客户端中的“工具详情”视图。
• 示例在哪里？ 查看此代码库中的 examples/，获取入门集成示例。

---

示例

examples/ 目录包含了如何将 SignNow MCP Server 与常用 AI Agent 框架集成的可运行示例：

• LangChain - 使用 langchain-mcp-adapters 与 LangChain Agent 集成
• LlamaIndex - 使用 llama-index-tools-mcp 与 LlamaIndex Agent 集成
• SmolAgents - 使用原生 MCP 支持与 SmolAgents 框架集成

每个示例都演示了如何：

• 将 MCP 服务作为子进程启动
• 将 MCP 工具转换为框架专用的工具格式
• 创建可使用 SignNow 功能的 Agent
• 处理环境变量配置

运行示例：

# Make sure you have the required dependencies installed
pip install langchain-openai langchain-mcp-adapters  # for LangChain example
pip install llama-index-tools-mcp                   # for LlamaIndex example  
pip install smolagents                              # for SmolAgents example

# Set up your .env file with SignNow credentials and LLM configuration
# Then run the example
python examples/langchain/langchain_example.py
python examples/llamaindex/llamaindex_example.py
python examples/smolagents/stdio_demo.py

---

实用资源

示例应用

探索可直接使用的示例应用，快速测试如何通过 SignNow API 在软件中准备、签署和发送文档。

试用示例应用。

API 文档

查找有关 SignNow API 请求、参数、代码示例和可能错误的技术详情。通过详细指南和用例了解更多 API 功能。

阅读 API 文档。

SignNow API Helper MCP

连接 AI 以访问 API 文档、为复杂签署工作流生成代码，并自动排查集成错误。 访问 API Helper MCP

---

许可证

MIT — 参见 LICENSE.md。

---

关于 SignNow MCP Server — 由 SignNow 团队维护。欢迎通过 GitHub 拉取请求提交问题和贡献。

---