1. 项目概述打通Dify与MCP的桥梁如果你正在使用Dify构建AI工作流同时又希望能在Claude Desktop、Cursor这类支持MCPModel Context Protocol的客户端里直接调用这些工作流那么你很可能已经遇到了一个痛点如何在不同的AI工具之间优雅地“搬运”你的智能体手动复制粘贴不仅效率低下还破坏了对话的连贯性。这正是YanxingLiu/dify-mcp-server这个项目要解决的核心问题。它是一个轻量级的MCP服务器实现专门设计用来将你在Dify平台上创建的工作流无缝地暴露为MCP客户端如Claude可以直接调用的“工具”。简单来说这个项目就像一座精心设计的桥梁。桥的一头连接着你部署在Dify上的各种功能——可能是智能客服、内容生成、数据分析流程桥的另一头则连接着Claude等AI助手。通过这座桥Claude在与你对话时就能像调用一个内置函数一样轻松触发远在Dify服务器上运行的复杂工作流并将结果带回对话中。这极大地扩展了Claude等工具的能力边界让你能在一个统一的界面里调度由不同技术栈构建的AI能力。我最初接触这个项目是因为我需要让Claude能帮我处理一些涉及内部知识库查询和格式化报告生成的特定任务。这些任务在Dify里已经用工作流实现得很完善了但每次都要切换到浏览器去操作非常打断思路。这个MCP服务器完美地解决了我的问题。它本质上是一个适配器遵循MCP协议规范将Dify的OpenAPI接口封装成MCP标准的Tools从而实现了跨平台的工具调用。接下来我会详细拆解它的配置、使用以及我在实际部署中积累的一些经验。2. 核心原理与架构设计解析2.1 MCP协议AI工具的“通用插座”要理解这个项目首先得弄明白MCP是什么。你可以把MCP想象成AI世界里的“USB-C接口”或“通用插座”协议。在它出现之前每个AI应用如Claude、Cursor如果想接入外部工具如搜索引擎、数据库、Dify工作流都需要开发者为其编写特定的插件或集成代码这就像每个电器都需要专属的充电器非常麻烦且不通用。MCP协议由Anthropic提出旨在标准化AI模型与外部工具、数据源之间的通信方式。它定义了一套简单的JSON-RPC over STDIO标准输入输出的通信规范。一个MCP服务器Server负责提供一系列工具Tools和资源Resources而MCP客户端Client如Claude Desktop则通过这个标准协议去发现和调用这些工具。这样一来工具开发者只需要编写一个符合MCP标准的服务器就能让所有支持MCP的客户端无需修改即可使用实现了“一次编写处处运行”。dify-mcp-server扮演的正是这个“服务器”角色。它启动后会通过STDIO与Claude Desktop等客户端建立连接。当客户端询问“你有什么工具可用”时服务器会根据配置的Dify App SKs动态地宣告对应的工具列表。每个Dify工作流都会对应一个MCP工具。2.2 项目工作流程与数据流转这个服务器的核心工作流程可以概括为以下几个步骤理解这个过程对后续的故障排查非常有帮助初始化与配置加载服务器启动时首先读取配置。无论是通过环境变量DIFY_BASE_URL和DIFY_APP_SKS还是通过config.yaml文件其目的都是获取两个关键信息Dify云服务或自建服务的API入口地址以及一个或多个Dify应用的密钥SK。每个SK唯一对应一个Dify工作流。工具发现Tool Listing当MCP客户端连接上来并请求列出可用工具时服务器并不会立即去Dify端查询。它只是简单地将配置中的每个SK映射成一个预设工具名的MCP工具声明例如dify_workflow_app-sk1。这意味着工具的名称和描述在服务器启动时就固定了与实际Dify工作流的名称可能无关关联的关键是SK本身。工具调用Tool Invocation这是最关键的环节。当用户在Claude中要求调用某个Dify工具时Claude会将用户的输入作为参数。服务器收到调用请求后参数提取从MCP请求中提取inputs参数。这个inputs应该是一个JSON对象其结构必须与你目标Dify工作流所定义的输入变量相匹配。API调用服务器构造一个HTTP POST请求发送到{DIFY_BASE_URL}/workflows/run。请求体中包含inputs参数和对应的app_sK即工具名中隐含的SK。这里使用的是Dify的公开工作流运行API。响应处理服务器接收Dify API返回的JSON响应提取出工作流的输出内容通常是outputs字段下的数据。结果返回将提取出的输出内容封装成MCP协议规定的格式通过STDIO返回给客户端。Claude便会将这个结果呈现给用户。整个过程中dify-mcp-server本身不执行任何AI推理或业务逻辑它只是一个协议转换器和请求路由器。所有的智能处理都发生在Dify云端或你的私有部署节点上。这种设计使得服务器非常轻量、稳定且易于维护。2.3 配置方式的深层考量环境变量 vs. YAML文件项目提供了两种配置方式这不仅仅是方便性的选择背后有不同的使用场景和最佳实践。环境变量配置这是文档中推荐的、尤其适合云托管平台的方式。它的最大优势在于安全性与容器化友好。在Docker、Kubernetes或一些Serverless平台中通过环境变量注入密钥是标准做法。你可以轻松地使用平台的秘密管理服务如AWS Secrets Manager, Kubernetes Secrets来设置DIFY_APP_SKS避免将敏感信息硬编码在配置文件里并存入代码仓库。此外动态调整也更方便比如在集群中滚动更新Pod时只需更新Secret无需重新构建镜像或分发配置文件。YAML文件配置这种方式更适合本地开发、测试或固定环境的部署。它的优势在于可读性和结构化。一个config.yaml文件可以清晰地列出多个SK并添加注释说明每个SK对应的具体工作流功能便于团队协作和知识传承。对于需要管理大量不同Dify工作流的场景维护一个配置文件可能比管理一长串环境变量更清晰。我的实操心得我个人的做法是在开发测试阶段使用config.yaml因为需要频繁修改和注释。而在生产环境部署时则统一使用环境变量并将DIFY_APP_SKS的值存储在Vault中通过CI/CD流水线在部署时注入。这样既保证了开发便利性又确保了生产环境的安全。3. 详细安装与配置指南3.1 前期准备获取Dify配置信息在安装MCP服务器之前你必须先准备好Dify端的“通行证”。这里假设你已经有一个可用的Dify工作流。获取DIFY_BASE_URLDify Cloud用户你的DIFY_BASE_URL固定为https://cloud.dify.ai/v1。这是Dify官方云服务的API入口。自建Dify用户如果你在自己的服务器上部署了Dify那么BASE_URL就是你服务器的API地址通常是http(s)://你的域名或IP:端口/v1。你可以在Dify后台的“设置” - “API密钥”页面找到完整的API基础地址。获取DIFY_APP_SKS进入Dify控制台找到你想要暴露的工作流所属的“应用”。点击进入该应用在左侧菜单找到“访问API”或“API密钥”选项。你会看到“App Secret Key”有时简称App SK或SK。复制它。这个密钥是调用该应用工作流的凭证。如果你有多个工作流分布在多个应用或同一应用的不同版本你需要收集每个工作流对应的SK。3.2 配置方式详解与实操3.2.1 方法一使用环境变量推荐用于生产环境这是最直接的方式尤其适合在终端会话中快速测试。你只需要在启动客户端前在同一个shell环境中设置好变量即可。# 设置Dify API基础地址 export DIFY_BASE_URLhttps://cloud.dify.ai/v1 # 设置一个或多个App SK用英文逗号分隔中间不要有空格 export DIFY_APP_SKSsk-xxxxxx-app1,sk-yyyyyy-app2关键细节DIFY_APP_SKS的值是一个纯字符串多个SK之间用逗号分隔不能包含空格。例如sk1,sk2,sk3是正确的而sk1, sk2, sk3或[sk1,sk2]是错误的。这些环境变量是临时的只对当前终端会话有效。关闭终端后就会失效。为了持久化你需要将它们写入你的shell配置文件如~/.bashrc,~/.zshrc或者使用下一节提到的客户端配置方式。3.2.2 方法二使用config.yaml文件推荐用于本地管理对于需要管理多个SK或者希望配置有更好可读性和版本控制的场景YAML文件是更好的选择。创建配置目录和文件 文档中给出的命令是一步到位的方案它会创建目录和文件。我们一步步拆解以便理解# 1. 为dify-mcp-server创建一个专属配置目录。~/.config是存放用户级配置的标准位置。 mkdir -p ~/.config/dify-mcp-server # 2. 使用cat命令和EOF标记创建config.yaml文件并写入内容。 # 注意缩进在YAML中至关重要必须使用空格通常两个空格。 cat ~/.config/dify-mcp-server/config.yaml EOF dify_base_url: https://cloud.dify.ai/v1 dify_app_sks: - sk-xxxxxx-app1 # 这是用于智能客服的工作流 - sk-yyyyyy-app2 # 这是用于周报生成的工作流 # 你可以继续添加更多SK EOF # 3. 验证文件是否创建成功 cat ~/.config/dify-mcp-server/config.yaml理解YAML结构dify_base_url和dify_app_sks是顶级的键。dify_app_sks的值是一个列表List以短横线-开头表示列表项。这与环境变量的逗号分隔字符串格式完全不同。以#开头的是注释你可以在这里记录每个SK对应的具体功能这对于后期维护非常有用。3.3 客户端安装与配置实战项目提供了两种运行方式核心区别在于依赖管理工具uv的使用模式。3.3.1 基础准备安装uvuv是一个用Rust编写的、极其快速的Python包安装器和项目管理器。无论是哪种方法你都需要先安装它。# 使用官方一键安装脚本适用于macOS/Linux curl -Ls https://astral.sh/uv/install.sh | sh安装完成后重启你的终端或者运行source ~/.bashrc或source ~/.zshrc来让uv命令生效。你可以通过uv --version来验证安装。3.3.2 方法一使用uvx最推荐无需克隆代码uvx是uv的一个子命令全称是“uv execute”。它的理念是“临时安装并运行”。你不需要手动克隆项目代码到本地uvx会从指定的源如Git仓库获取包临时安装到一个隔离的环境然后执行它。这类似于npx对于Node.js的作用。配置Claude Desktop 你需要编辑Claude Desktop的MCP服务器配置文件。文件通常位于macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json用文本编辑器打开这个文件如果不存在则创建然后添加如下配置块。这里演示使用环境变量直接配置的方式{ mcpServers: { dify-mcp-server: { command: uvx, args: [ --from, githttps://github.com/YanxingLiu/dify-mcp-server, dify_mcp_server ], env: { DIFY_BASE_URL: https://cloud.dify.ai/v1, DIFY_APP_SKS: sk-xxxxxx-app1,sk-yyyyyy-app2 } } } }配置解析command: uvx指定使用uvx命令来运行。args传递给uvx的参数。--from, githttps://...告诉uvx从哪个Git仓库地址获取包。dify_mcp_server指定要运行的包内的可执行模块名对应pyproject.toml中定义的入口点。env为这个MCP服务器进程设置的环境变量。这里直接写入了你的Dify密钥。使用config.yaml文件的uvx配置 如果你更喜欢用YAML文件并且已经创建好~/.config/dify-mcp-server/config.yaml可以这样配置{ mcpServers: { dify-mcp-server: { command: uvx, args: [ --from, githttps://github.com/YanxingLiu/dify-mcp-server, dify_mcp_server ], env: { CONFIG_PATH: /Users/你的用户名/.config/dify-mcp-server/config.yaml } } } }注意你必须将CONFIG_PATH的值替换成你电脑上config.yaml文件的绝对路径。~符号在JSON配置中可能不会被正确解析所以最好使用完整路径。3.3.3 方法二使用uv本地克隆项目这种方式适合需要修改源码、进行二次开发或者希望将依赖固定在本地的场景。克隆项目代码git clone https://github.com/YanxingLiu/dify-mcp-server.git cd dify-mcp-server配置Claude Desktop 编辑配置文件command改为uvargs需要指向你本地克隆的目录。{ mcpServers: { dify-mcp-server: { command: uv, args: [ --directory, /绝对路径/到你克隆的/dify-mcp-server, run, dify_mcp_server ], env: { DIFY_BASE_URL: https://cloud.dify.ai/v1, DIFY_APP_SKS: sk-xxxxxx-app1,sk-yyyyyy-app2 } } } }--directory此参数告诉uv在哪个目录下查找pyproject.toml来管理依赖和运行项目。runuv的子命令用于运行项目。同样环境变量可以直接写在env里也可以通过CONFIG_PATH指定YAML文件。两种方法对比与选择建议uvx强烈推荐给绝大多数用户。它省去了克隆和管理代码的步骤由uv自动处理依赖和缓存保证了运行环境的清洁和一致性。每次启动时uvx会检查是否有更新非常适合使用上游稳定版本。uv适用于开发者。如果你需要阅读源码、调试、或者基于此项目进行定制化修改例如添加日志、修改错误处理逻辑那么克隆代码并使用uv在本地运行是必须的。3.4 验证与使用完成配置后保存claude_desktop_config.json文件并完全重启Claude Desktop应用不是关闭窗口而是从任务栏/程序坞彻底退出再重新启动。这是关键一步因为MCP配置只在启动时加载。重启后新建一个对话。你可以尝试在输入框中输入/看看弹出的工具列表里是否出现了以dify_workflow_开头的工具后面跟着你SK的片段。如果出现了说明配置成功。现在你可以像使用其他工具一样使用它。例如Claude可能会这样调用我想生成一份周报。请调用Dify工作流帮我处理。Claude在理解你的意图后会自动选择对应的Dify工具并可能向你追问工作流所需的特定输入参数如“请提供本周的工作概要”。你提供参数后Claude就会通过MCP服务器调用Dify并将生成的结果返回给你。4. 高级配置、问题排查与实战经验4.1 多工作流管理与工具命名当你配置了多个DIFY_APP_SKS时服务器会为每个SK注册一个独立的MCP工具。工具的名称格式是dify_workflow_{SK}其中{SK}会被替换成你的App Secret Key。由于SK通常是一长串无意义的字符这会导致在Claude的工具列表里出现难以辨识的工具名例如dify_workflow_sk-abc123...。当前限制根据项目源码和协议MCP工具的名称在服务器初始化时就确定了且直接与SK绑定。目前dify-mcp-server项目本身没有提供自定义工具名称或描述的功能。工具的描述也是通用的。变通方案如果你觉得这影响使用体验可以考虑以下两种方式记忆SK尾缀虽然不友好但你可以通过SK的最后几位字符来区分。自行修改源码进阶如果你使用本地uv方式运行可以修改项目源码。在server.py或相关工具注册逻辑中将工具名称映射到一个你自定义的、更友好的名字字典。例如读取一个额外的配置文件将sk-abc123映射为generate_weekly_report。这需要一定的Python编程能力。我的实操心得在初期我只接入1-2个核心工作流通过SK尾缀尚可管理。当工作流超过5个时工具列表就会变得混乱。我最终采用了修改源码的方案增加了一个tool_alias.yaml配置文件让我可以用周报生成器、客服问答这样的中文名来调用工具体验提升巨大。希望未来官方能支持这个功能。4.2 网络连接与超时问题MCP服务器需要能够访问你配置的DIFY_BASE_URL。这可能会引发几种常见问题连接被拒绝 / 无法访问主机检查DIFY_BASE_URL是否正确特别是自建Dify时确保端口和路径 (/v1) 无误。尝试在终端用curl {DIFY_BASE_URL}/health测试连通性。SSL证书错误如果你使用自签证书的HTTPS地址Python的requests库可能会报SSL错误。对于测试环境一个快速的解决方法是修改服务器源码在请求Dify API时加上verifyFalse参数严重警告此方法不安全仅用于测试。生产环境请使用有效的证书。超时错误如果Dify工作流执行时间很长可能会超过MCP客户端或服务器的默认超时设置。目前dify-mcp-server似乎没有暴露超时配置参数。如果遇到超时你需要检查1) Dify工作流本身是否优化2) 考虑在Dify中设置异步调用让工作流立即返回一个任务ID然后通过其他方式查询结果。4.3 认证失败与参数错误这是最常遇到的问题通常体现在调用工具后返回错误信息。401 Unauthorized或Invalid API Key检查SK确认你使用的App SK是否正确、是否已启用。在Dify后台重新复制一遍。检查SK格式确保在环境变量中是逗号分隔无空格的字符串在YAML文件中是列表格式。一个常见的错误是在YAML中写成了dify_app_sks: sk1,sk2字符串而不是dify_app_sks: [sk1,sk2]列表。检查BASE_URL确保BASE_URL指向正确的环境Cloud vs. 自建。Dify Cloud的SK不能用在自建地址上反之亦然。400 Bad Request或工作流执行错误检查输入参数MCP工具调用时Claude会尝试构建一个inputsJSON对象。你必须确保这个对象的键值对完全符合Dify工作流所定义的输入变量。例如你的工作流如果有一个名为topic的字符串输入变量那么Claude传递的inputs就必须是{topic: 用户输入的主题}。在Claude中明确参数当你要求Claude调用Dify工具时最好清晰地告诉它需要哪些参数。例如“请调用周报生成工具输入参数是{week: 2024-05-20至2024-05-26, highlights: 完成了项目A的测试...}”。Claude有时能自动推断但明确指定最可靠。查看Dify日志登录Dify后台查看该工作流的运行历史记录里面会有更详细的错误信息能帮你定位是哪个节点出了问题。4.4 性能优化与稳定性建议连接池与复用dify-mcp-server本身很轻量但频繁调用Dify API可能会遇到网络延迟。虽然服务器源码可能没有显式配置HTTP连接池但底层的requests.Session在单进程内会保持连接复用。确保你的客户端如Claude Desktop不要频繁重启MCP服务器进程以利用连接复用。错误重试机制目前服务器可能没有内置重试逻辑。对于网络抖动造成的偶发失败可以考虑在Dify工作流的上游即你的使用习惯中进行重试或者未来在服务器源码中添加简单的重试装饰器。监控与日志默认的日志输出可能比较简单。对于生产环境建议修改源码集成像structlog或loguru这样的日志库将日志输出到文件并记录每次调用的SK可脱敏、输入摘要、耗时和状态便于监控和审计。4.5 常见问题速查表下表总结了部署和使用过程中最常见的问题及解决方法问题现象可能原因排查步骤与解决方案Claude重启后找不到Dify工具MCP配置未生效或格式错误1. 检查claude_desktop_config.json路径和格式可用JSON验证器。2.彻底重启Claude Desktop。3. 查看Claude Desktop的日志位置因系统而异通常可在设置中打开调试模式找到。调用工具时报Failed to start serveruv或uvx命令未安装或路径错误1. 在终端执行uv --version确认安装成功。2. 在MCP配置中command字段确保是uv或uvx。3. 如果使用uv检查--directory指向的路径是否存在且包含pyproject.toml。调用工具时报401认证错误API密钥错误或配置格式不对1. 确认SK准确无误且在Dify中处于“启用”状态。2.检查配置格式环境变量是逗号分隔字符串YAML文件是列表。3. 确认DIFY_BASE_URL与SK所属环境匹配。调用工具时报400请求错误输入参数不符合Dify工作流定义1. 在Dify中检查目标工作流的输入变量名和类型。2. 在Claude中调用时明确指定符合规范的inputsJSON对象。3. 查看Dify工作流运行日志获取具体错误。工具执行成功但返回空或错误内容Dify工作流内部节点错误或输出格式问题1. 直接通过Dify界面测试相同输入看工作流是否正常。2. 检查工作流最后一个“回答”或“输出”节点的配置。3. MCP服务器默认提取响应中的outputs字段确保你的工作流输出包含该字段。工具调用超时Dify工作流执行时间过长或网络延迟1. 优化Dify工作流复杂度减少耗时。2. 对于长耗时任务考虑在Dify中改为异步调用模式。3. 目前服务器超时设置不可调此为已知限制。5. 进阶应用场景与未来展望5.1 场景拓展构建你的AI能力中枢dify-mcp-server的价值远不止于连接Claude和Dify。它的核心思想是标准化接入。一旦你的Dify工作流通过MCP暴露出来任何支持MCP协议的客户端都能调用它们。Cursor IDE在编写代码时可以直接让Cursor调用Dify工作流来生成代码注释、编写测试用例、解释复杂算法。其他MCP客户端随着MCP生态的发展未来会有更多AI应用支持该协议。你现在构建的Dify-MCP桥梁可以让你在未来平滑地将AI能力迁移到新的工具上。自动化流程你可以编写脚本直接与MCP服务器通信通过STDIO从而在CI/CD流水线、定时任务等场景中程序化地触发复杂的Dify AI工作流。5.2 结合其他MCP服务器能力聚合MCP的魅力在于可扩展性。你可以在Claude Desktop中同时配置多个MCP服务器比如dify-mcp-server提供自定义AI工作流。mcp-server-filesystem让Claude能读写本地文件。mcp-server-sqlite让Claude能查询数据库。这样Claude在一次对话中就能同时拥有文件处理、数据查询和专用AI工作流的能力。你可以指示Claude“读取我~/projects/report.md文件中的本周数据调用Dify的‘数据分析’工具进行处理然后将结果保存到新的文件中。” 这一切可以在一个连贯的对话中完成。5.3 对项目未来发展的期待目前这个项目是一个极简而有效的实现满足了核心需求。从社区和自身使用角度我希望未来能看到以下增强工具元信息自定义允许在配置中为每个SK指定一个易读的工具名、描述和参数Schema这样在客户端列表里会更友好Claude也能更好地理解何时该调用哪个工具。更灵活的配置支持从远程URL或加密文件读取配置更好地与云原生密钥管理服务集成。增强的容错与重试内置对网络波动和Dify API暂时性失败的重试机制。执行状态与异步支持对于长任务提供轮询任务状态或通过Webhook回调的能力。这个项目展示了开源社区如何通过一个轻巧的适配器解决AI工具间互联互通的实际问题。它可能没有复杂的界面和庞大的功能但精准地命中了一个痛点并以优雅的方式解决了它。随着MCP协议的普及这类“连接器”的价值会愈发凸显。