JinDaGe - sn-mcp-server MCP Details

article

README

🚀 SignNow MCP 服务器

SignNow REST API 能够为签署者、准备者和发送者提供无缝的电子签名体验。它支持预填充文档、为多个签署者创建嵌入式品牌工作流程、请求付款以及实时跟踪签名状态，确保在任何设备上都能实现简单、安全且直观的签署操作。

利用 SignNow API 可实现的功能：

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

🚀 快速开始

前提条件

拥有 SignNow 账户。您可以创建一个免费开发者账户。
具备 SignNow 凭证：您需要账户电子邮件、密码以及应用程序的基本授权令牌。入门指南。
拥有一个活跃的 SignNow API 应用程序。
系统中安装了 Python 3.11 或更高版本（可使用 python3 --version 进行检查）
安装了 UVX（可使用 uvx --version 进行检查）。建议使用它以实现最快的设置。
配置好环境变量
如果您的客户端支持可流式传输的 HTTP，您可以使用预部署的服务器 URL https://mcp-server.signnow.com/mcp，而无需在本地运行。

快速运行（uvx）

如果您使用 uv，可以在不安装软件包的情况下运行服务器：

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

1. 设置环境变量

# 使用您的 SignNow 凭证创建 .env 文件
# 如果您有源代码，可以从 env.example 复制
# 或者手动创建包含所需变量的 .env 文件（请参阅下面的环境变量部分）

2. 安装并运行

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

# 从 PyPI 安装软件包
pip install signnow-mcp-server

# 以独立模式运行 MCP 服务器
sn-mcp serve

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

# 1) 克隆并配置
git clone https://github.com/signnow/sn-mcp-server.git
cd sn-mcp-server
cp .env.example .env
# 在 .env 中填写您的值

# 2) 安装（开发时可编辑）
pip install -e .

# 3) 作为 STDIO MCP 服务器运行（推荐用于本地工具和检查器）
sn-mcp serve

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

本地/远程（HTTP）

# 在 127.0.0.1:8000 上启动 HTTP 服务器
sn-mcp http

# 自定义主机/端口
sn-mcp http --host 0.0.0.0 --port 8000

# 开发重载
sn-mcp http --reload

默认情况下，可流式传输的 HTTP MCP 端点在 /mcp 下提供服务。示例 URL：

http://localhost:8000/mcp

Docker

# 构建
docker build -t sn-mcp-server .

# 以 HTTP 模式运行（推荐用于容器）
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

# 仅运行 MCP 服务器
docker-compose up sn-mcp-server

# 同时运行两个服务（如果已定义）
docker-compose up

✨ 主要特性

模板与组

浏览所有模板和模板组
从模板创建文档或组（包括一次性流程）

邀请与嵌入式用户体验

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

状态与检索

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

传输方式

STDIO（最适合本地客户端）
可流式传输的 HTTP（最适合 Docker/远程）

📚 详细文档

配置

将 .env.example 复制为 .env 并填写值。所有设置在启动时通过 pydantic-settings 进行验证。

认证选项

1) 用户名/密码（推荐用于桌面开发流程）

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

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

SIGNNOW_CLIENT_ID=<client_id>
SIGNNOW_CLIENT_SECRET=<client_secret>
# + 以下是 OAuth 服务器和 RSA 设置

通过某些桌面客户端运行时，可能仅支持用户/密码认证。

SignNow 与 OAuth 设置

# SignNow 端点（显示默认值）
SIGNNOW_APP_BASE=https://app.signnow.com
SIGNNOW_API_BASE=https://api.signnow.com

# 可选的直接 API 令牌（正常使用不需要）
SIGNNOW_TOKEN=<access_token>

# OAuth 服务器（如果启用 OAuth 模式）
OAUTH_ISSUER=<your_issuer_url>
ACCESS_TTL=3600
REFRESH_TTL=2592000
ALLOWED_REDIRECTS=<comma,separated,uris>

# 用于 OAuth 的 RSA 密钥（生产环境中至关重要）
OAUTH_RSA_PRIVATE_PEM=<PEM content>
OAUTH_JWK_KID=<key id>

生产环境密钥管理

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

客户端设置

VS Code — GitHub Copilot（代理模式）/ 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"
    }
  }
}

然后打开聊天窗口 → 代理模式，启用 signnow 工具，并在提示中使用它们。

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

Claude Desktop

使用桌面扩展或手动 MCP 配置（开发者 → 编辑配置）。

步骤：

打开 Claude Desktop → 开发者 → 编辑配置
在 mcpServers 下添加一个新的服务器条目
保存并重启 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 上部署并运行此服务器：

步骤：

打开 Glama 上的服务器页面：Glama 上的 sn-mcp-server
点击红色的“部署服务器”按钮
在环境变量中提供：
- SIGNNOW_USER_EMAIL
- SIGNNOW_PASSWORD
- SIGNNOW_API_BASIC_TOKEN
- （其他变量可以保留默认值）
在 Glama 中创建访问令牌并复制端点 URL。它将类似于：

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

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

MCP 检查器（测试）

非常适合直观地探索工具和模式。

# 启动检查器（在本地主机上打开 UI）
npx @modelcontextprotocol/inspector

# 连接（STDIO）：在本地运行服务器并进行连接
sn-mcp serve

# 或者连接（HTTP）：使用 http://localhost:8000/mcp

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

工具

每个工具都有简洁的描述；使用 MCP 客户端（例如检查器）查看确切的 JSON 模式。

list_all_templates — 列出具有简化元数据的模板和模板组。支持 limit/offset 分页（默认：每页 50 项）。
list_documents — 浏览您的文档、文档组和状态。支持 limit/offset 分页（默认：每页 50 项）。
create_from_template — 从模板/组创建文档或组。
send_invite — 发送电子邮件邀请（文档或组），支持有序收件人。
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 — 获取文档或组的当前邀请状态/步骤。
get_document_download_link — 获取直接下载链接（组的合并输出）。
get_signing_link — 获取文档或文档组的签署链接。
get_document — 获取具有字段值的规范化文档/组结构。
update_document_fields — 预填充单个文档中的文本字段。

提示：从 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 检查器 或您的客户端的“工具详情”视图。
示例在哪里？ 请参阅此仓库中的 examples/ 目录以获取入门集成示例。

💻 使用示例

examples/ 目录包含了如何将 SignNow MCP 服务器与流行的 AI 代理框架集成的实际示例：

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

每个示例都展示了如何：

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

要运行示例：

# 确保您已安装所需的依赖项
pip install langchain-openai langchain-mcp-adapters  # 对于 LangChain 示例
pip install llama-index-tools-mcp                   # 对于 LlamaIndex 示例  
pip install smolagents                              # 对于 SmolAgents 示例

# 使用 SignNow 凭证和 LLM 配置设置您的 .env 文件
# 然后运行示例
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 助手 MCP

将您的 AI 连接到该助手，以访问 API 文档、为复杂的签署工作流程生成代码并自动排除集成错误。访问 API 助手 MCP

📄 许可证

本项目采用 MIT 许可证 — 请参阅 LICENSE.md。

关于

SignNow MCP 服务器由 SignNow 团队维护。欢迎通过 GitHub 拉取请求提交问题和贡献代码。