使用说明

DocuSign MCP服务器

实验性 用于DocuSign eSignature API的模型上下文协议（MCP）服务器，使用Python+FastMCP构建。使用JWT OAuth进行真正的服务器到服务器身份验证（无刷新令牌）。

⚠️ 状态和免责声明

实验性：未准备好生产；无SLA；API和行为可能会改变。
与DocuSign无关联：这是一种社区融合。DocuSign是DocuSignneneneba公司的商标。
安全：做不泄露秘密。将私钥和令牌视为敏感；使用秘密管理器。 使用风险自负。

特性

🔐 JWT服务器到服务器身份验证 -无刷新令牌，完全无头操作
📄 信封管理 -创建、发送、跟踪和管理信封
📋 模板操作 -列出并使用DocuSign模板
📥 文件处理 -上传、下载和管理文档
🔌 MCP协议 -用于AI助手集成的标准stdio传输
✅ 单元测试 -通过模拟实现全面的pytest覆盖

需求

Python 3.11+
uv 包管理器（推荐）或 pip
DocuSign开发人员帐户（演示或制作）
已配置JWT集成密钥
用于JWT身份验证的RSA密钥对（您生成此密钥对）
管理员同意 signature + impersonation 范围

安装

使用紫外线（推荐）

# Install from GitHub
uvx --from git+https://github.com/luthersystems/mcp-server-docusign mcp-server-docusign

# Or install in project
uv pip install git+https://github.com/luthersystems/mcp-server-docusign

使用pip

pip install git+https://github.com/luthersystems/mcp-server-docusign

开发安装

git clone https://github.com/luthersystems/mcp-server-docusign.git
cd mcp-server-docusign
uv pip install -e ".[dev]"

配置

环境变量

使用环境变量配置服务器（请参阅配置参考):

# Authentication base URL
DS_AUTH_BASE=https://account-d.docusign.com  # Demo environment
# DS_AUTH_BASE=https://account.docusign.com  # Production environment

# Integration credentials
DS_INTEGRATION_KEY=<your-integration-key-guid>
DS_USER_ID=<impersonated-user-guid>

# OAuth configuration
DS_OAUTH_SCOPE="signature impersonation"

# Private key path
DS_PRIVATE_KEY_PATH=./private.key

# Token expiration (seconds)
DS_TOKEN_EXP_SECS=3600

DocuSign设置

1.创建或选择集成密钥

登录到 DocuSign管理控制台（演示）或管理控制台（生产）
导航至设置 → 应用程序和密钥
要么：
- 使用现有的集成密钥 从列表中（例如。， 1fa2e333-fdc2-411c-ab65-18ed437eae53)
- 或者创建一个新的：单击 “+添加应用程序和集成密钥”
注意/复制 集成密钥 （这是你的 DS_INTEGRATION_KEY)

2.生成RSA密钥对

# Generate private key
openssl genrsa -out private.key 2048

# Extract public key
openssl rsa -in private.key -pubout -out public.key

3.配置集成

在DocuSign管理控制台中，选择您的集成
在...之下认证，选择 JWT（JSON Web令牌）
上传您的 public.key 文件（在步骤2中生成）
在...之下 重定向URI，单击“添加URI”并添加： https://www.docusign.com
- 重要：重定向URI必须与您在同意URL中使用的内容完全匹配（没有尾随斜线）
点击保存在底部

4.授予管理员同意（需要一次）

关键的：在服务器可以运行之前，帐户管理员必须同意 signature 和 impersonation 范围。

步骤：

确保已配置重定向URI 在上述步骤3中（例如。， https://www.docusign.com)
构建同意URL （替换 <INTEGRATION_KEY> 使用您的实际集成密钥）：
```
https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature%20impersonation&client_id=<INTEGRATION_KEY>&redirect_uri=https://www.docusign.com
```
- 对于 演示/沙盒：使用 https://account-d.docusign.com
- 对于生产：使用 https://account.docusign.com
- 这 redirect_uri 参数 必须完全匹配 您在步骤3中添加的内容
访问URL 以DocuSign管理员身份登录时在浏览器中
点击“允许访问” 同意
您将被重定向到重定向URI（可能会显示错误页面，但没关系-同意已授予）
这是一次性操作 -除非你撤销同意或更改范围，否则你不需要再做一次

模板权限疑难解答：

如果访问模板时出现401错误，请确保：

用户具有模板权限 在DocuSign中：
- 首选设置 → 用户 → 选择用户
- 在...之下权限，确保启用了“允许用户创建和管理模板”
- 保存更改
帐户具有模板功能 已启用（可能需要某些DocuSign计划级别）
OAuth作用域是正确的:
- 这 signature 范围（包含在我们的同意URL中）涵盖模板访问
- 如果您修改了范围，可能需要重新授予同意

5.获取用户ID

可以找到用户ID（GUID）：

在DocuSign管理控制台中→ 用户 → 选择用户→ URL中的用户GUID
或通过API调用 /oauth/userinfo 初始身份验证后

运行服务器

标准模式（默认）

# Set environment variables
export DS_AUTH_BASE=https://account-d.docusign.com
export DS_INTEGRATION_KEY=your-integration-key
export DS_USER_ID=your-user-guid
export DS_PRIVATE_KEY_PATH=./private.key

# Run server
mcp-server-docusign

默认情况下，服务器在stdio模式下运行，适用于Claude Desktop或Cursor等MCP客户端。

MCP检验员测试

npx -y @modelcontextprotocol/inspector uvx --from git+https://github.com/luthersystems/mcp-server-docusign mcp-server-docusign

可用工具

信封操作

`create_envelope_from_template`

从DocuSign模板创建信封。

参数：

template_id （string）：要使用的模板ID
email_subject （string）：电子邮件主题行
role_assignments （数组）：角色分配列表
- roleName （string）：模板中的角色名称
- name （string）：收件人的全名
- email （string）：收件人的电子邮件
- clientUserId （字符串，可选）：用于嵌入式签名
email_blurb （字符串，可选）：电子邮件正文
status （字符串，默认值：“send”）：“sent”或“created”

退货： {envelopeId, status, statusDateTime}

`create_envelope_from_documents`

从文档创建信封（不使用模板）。

参数：

documents （array）：文档列表
- name （string）：文档名称
- documentId （字符串）：文档ID（例如，“1”、“2”）
- fileExtension （string）：文件扩展名（例如“pdf”）
- documentBase64 （string）：Base64编码内容
recipients （对象）：收件人列表
- signers （array）：签名者列表
email_subject （string）：电子邮件主题
email_blurb （字符串，可选）：电子邮件正文
status （字符串，默认值：“send”）：“sent”或“created”

退货： {envelopeId, status, statusDateTime}

`get_envelope_status`

获取信封的状态和元数据。

参数：

envelope_id （字符串）：信封ID

退货： {envelopeId, status, emailSubject, createdDateTime, sentDateTime, completedDateTime, ...}

`list_envelopes`

列出带有可选过滤器的信封。

参数：

from_date （字符串，可选）：开始日期（ISO 8601）
to_date （字符串，可选）：结束日期（ISO 8601）
status （字符串，可选）：状态筛选器

退货： {envelopes[], resultSetSize, totalSetSize}

模板操作

`list_templates`

列出可用的DocuSign模板。

参数：

search_text （字符串，可选）：按名称筛选

退货： {templates[], resultSetSize, totalSetSize}

`get_template_definition`

获取完整的模板定义。

参数：

template_id （string）：模板ID

退货： {templateId, name, description, roles[], documents[], ...}

文档操作

`list_envelope_documents`

列出信封中的所有文档。

参数：

envelope_id （字符串）：信封ID

退货： {envelopeId, documents[]}

`download_envelope_document`

从信封中下载文档。

参数：

envelope_id （字符串）：信封ID
document_id （string）：文档ID

退货： {envelopeId, documentId, contentBase64, sizeBytes}

示例用法

与Claude Desktop一起使用

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "docusign": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/luthersystems/mcp-server-docusign",
        "mcp-server-docusign"
      ],
      "env": {
        "DS_AUTH_BASE": "https://account-d.docusign.com",
        "DS_INTEGRATION_KEY": "your-integration-key",
        "DS_USER_ID": "your-user-guid",
        "DS_PRIVATE_KEY_PATH": "/path/to/private.key"
      }
    }
  }
}

示例提示

“列出我的DocuSign模板”

“使用John Doe从模板[template-id]创建信封(john@example.com)作为签名者1”

“检查信封的状态[信封id]”

“从信封[信封id]下载文档1”

发展

运行测试

# Install dev dependencies
uv pip install -e ".[dev]"

# Run unit tests (no credentials needed)
pytest

# Run with coverage
pytest --cov=mcp_server_docusign --cov-report=html

# Run linter
ruff check .

# Format code
ruff format .

集成测试（可选）

集成测试验证真实的DocuSign API身份验证。他们是 默认情况下跳过 并且仅在您提供真实凭据时运行。

要启用集成测试，请执行以下操作：

复制 .env.example 到 .env:
```
cp .env.example .env
```

在中填写您的DocuSign凭据 .env:

# Required fields (choose ONE of the two private key options):

# Option 1: File path (recommended for local development)
DS_AUTH_BASE=https://account-d.docusign.com
DS_INTEGRATION_KEY=your-integration-key-guid
DS_USER_ID=your-user-guid
DS_PRIVATE_KEY_PATH=./private.key
DS_OAUTH_SCOPE=signature impersonation

# Option 2: Base64-encoded key (recommended for CI/CD)
# DS_PRIVATE_KEY=LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0t...

创建RSA密钥对：

openssl genrsa -out private.key 2048
openssl rsa -in private.key -pubout -out public.key

上传 public.key 签署DocuSign并授予管理员同意（请参阅 .env.example 详细说明）
运行集成测试：
```
pytest tests/test_integration.py -v
```

CI/CD设置（GitHub操作）

要在GitHub Actions中运行集成测试，请执行以下操作：

将私钥编码为base64：

# macOS/Linux
base64 -i private.key | tr -d '\n' | pbcopy

# This copies the base64-encoded key to your clipboard

添加GitHub存储库机密：
- 转到您的仓库→ 设置 → 秘密和变量 → 行动
- 添加以下机密：
  - DS_AUTH_BASE: https://account-d.docusign.com
  - DS_INTEGRATION_KEY：您的集成密钥GUID
  - DS_USER_ID：您的用户GUID
  - DS_PRIVATE_KEY：base64编码的私钥（来自步骤1）
CI工作流将自动运行集成测试 当这些秘密出现时

备注：在fork的PR中，集成测试将被跳过（出于安全考虑），但将在主/开发分支的推送上运行。

集成测试验证了什么：

✅ JWT身份验证使用您的凭据
✅ 可以成功获取访问令牌
✅ 可以检索帐户ID
✅ 正确发现基本URI
✅ API调用工作（测试 list_templates)
✅ 令牌刷新机制工作

备注：集成测试需要DocuSign开发人员帐户（建议使用演示环境）。

模板访问故障排除（401错误）：

如果 test_list_templates 跳过测试，出现401错误，这表示未配置模板访问权限。要修复：

检查用户权限 在DocuSign管理控制台中：
- 首选https://admindemo.docusign.com/ → 用户
- 点击您的用户→ 权限
- 确保这些功能已启用：
  - ✅ “允许用户创建和管理模板”
  - ✅ “允许用户使用模板”
  - ✅ “允许用户共享模板”
- 保存更改
验证OAuth作用域：The signature impersonation 范围已涵盖模板访问。如果您更改了范围，可能需要重新授予管理员同意。
账户计划限制：某些DocuSign演示帐户可能具有有限的API访问权限。模板应该适用于大多数开发人员帐户，但如果问题仍然存在，则可能是帐户级别的限制。

备注：跳过模板测试不会阻止MCP服务器运行。一旦部署了适当的生产凭据和权限，模板操作将正常工作。

项目结构

mcp-server-docusign/
├── src/mcp_server_docusign/
│   ├── __init__.py
│   ├── server.py           # Main FastMCP server
│   ├── config.py           # Configuration management
│   ├── docusign_client.py  # JWT auth & API client
│   └── tools/
│       ├── envelopes.py    # Envelope tools
│       ├── templates.py    # Template tools
│       └── documents.py    # Document tools
├── tests/
│   ├── test_envelopes.py
│   ├── test_templates.py
│   └── test_documents.py
├── pyproject.toml
└── README.md

故障排除

“获取JWT令牌失败”

验证是否已授予管理员同意
检查集成密钥是否正确
确保公钥上传到DocuSign
验证用户GUID是否正确

“找不到用户的帐户”

用户ID必须有效且处于活动状态
检查用户是否具有适当的权限
确保授予模拟范围

“身份验证失败”

验证私钥是否与上传的公钥匹配
检查私钥文件路径是否正确
确保密钥文件可读

“连接超时”

检查互联网连接
验证防火墙设置
尝试演示环境(account-d.docusign.com)首先

安全最佳实践

从不提交私钥 -使用 .gitignore 和环境变量
使用机密管理 -将凭据存储在安全保管库中（AWS Secrets Manager等）
定期旋转按键 -定期生成新的密钥对
限制令牌寿命 -对敏感操作使用较短的过期时间
监控API使用情况 -检查DocuSign仪表板是否有异常活动
使用演示环境 -生产前使用模拟账户进行测试

建筑

语言：Python 3.11+
框架：FastMCP
API客户端：官方DocuSign Python SDK(docusign-esign)
认证：JWT服务器到服务器OAuth
运输：stdio（MCP协议）
测试：带模拟的pytest

参考文献

许可证

麻省理工学院

贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支
添加新功能的测试
确保所有测试通过
提交拉取请求

支持

这是一个实验性的社区项目。有关DocuSign API问题，请参阅 DocuSign开发者中心.

使用说明

DocuSign MCP服务器

⚠️ 状态和免责声明

特性

需求

安装

使用紫外线（推荐）

使用pip

开发安装

配置

环境变量

DocuSign设置

1.创建或选择集成密钥

2.生成RSA密钥对

3.配置集成

4.授予管理员同意（需要一次）

5.获取用户ID

运行服务器

标准模式（默认）

MCP检验员测试

可用工具

信封操作

create_envelope_from_template

create_envelope_from_documents

get_envelope_status

list_envelopes

模板操作

list_templates

get_template_definition

文档操作

list_envelope_documents

download_envelope_document

示例用法

与Claude Desktop一起使用

示例提示

发展

运行测试

集成测试（可选）

CI/CD设置（GitHub操作）

项目结构

故障排除

“获取JWT令牌失败”

“找不到用户的帐户”

“身份验证失败”

“连接超时”

安全最佳实践

建筑

参考文献

许可证

贡献

支持

相关 MCP

文档管理服务

区块链数据查询服务

文档管理服务器

模型上下文协议服务器

文档版本助手

Google文档管理服务

`create_envelope_from_template`

`create_envelope_from_documents`

`get_envelope_status`

`list_envelopes`

`list_templates`

`get_template_definition`

`list_envelope_documents`

`download_envelope_document`