基于MCP协议的Upwork AI代理服务器：自动化自由职业工作流

1. 项目概述：一个为AI代理打通Upwork工作流的MCP服务器

如果你是一名自由职业者，或者正在尝试用AI工具来优化你的接单流程，那你一定对每天在Upwork这类平台上重复的“刷单-评估-投递”工作感到疲惫。这个由AbbottDevelopments开源的upwork-mcp-server项目，就是为了解决这个痛点而生的。简单来说，它是一个遵循Model Context Protocol（MCP）标准的服务器，像一个智能翻译官和调度中心，让Claude这类AI助手能够直接、安全地调用Upwork的官方API，帮你自动化完成从发现机会、评估客户、撰写提案到管理合同和沟通的全流程。

想象一下，你不再需要手动刷新页面，AI可以基于你设定的技能、预算偏好和客户质量要求，7x24小时不间断地筛选海量职位；它还能深度分析招聘方的历史记录和评价，给每个机会打出一个客观的“风险-收益”综合分；甚至能帮你追踪提案状态、管理项目里程碑。这不仅仅是简单的通知机器人，而是一个深度集成到你的AI工作流中的专业“自由职业者副驾驶”。无论你是想提升接单效率的技术开发者，还是希望将AI能力融入现有业务系统的创业者，这个项目都提供了一个坚实、可扩展的起点。接下来，我将为你深入拆解它的设计思路、核心功能以及如何从零开始部署和使用它。

2. 核心设计思路与架构解析

2.1 为什么是MCP？标准化接口的价值

在深入代码之前，理解MCP（Model Context Protocol）的选择至关重要。你可以把MCP想象成AI世界的“USB-C”接口标准。在它出现之前，每个AI应用（如Claude Desktop、自定义的AI代理）想连接外部数据源（如Upwork、Notion、数据库），都需要各自编写一套特定的、紧耦合的集成代码，这导致了大量的重复劳动和兼容性问题。

MCP协议的核心价值在于标准化和解耦。它定义了一套清晰的规范，规定了一个“服务器”（Server）应该如何向“客户端”（Client）暴露其能力（即“工具”或“资源”）。对于upwork-mcp-server而言，它的角色就是MCP服务器，专门负责与Upwork API对话。而Claude Desktop或任何兼容MCP的客户端，则无需关心Upwork API的复杂细节（如OAuth流程、GraphQL查询语句、速率限制），它们只需要按照MCP的标准方式调用search_jobs或score_opportunity这样的工具名即可。

这种设计带来了几个显著优势：

1. 一次开发，多处使用：这个服务器一旦建成，可以同时服务于Claude Desktop、Cursor、Windsurf，甚至是未来任何新出现的MCP客户端。
2. 关注点分离：服务器开发者可以专注于Upwork领域的业务逻辑和API稳定性；客户端开发者则专注于AI的交互体验和提示工程。
3. 安全性：OAuth令牌等敏感信息被隔离在服务器进程中，不会泄露给AI客户端，降低了安全风险。

2.2 工具集设计：覆盖自由职业全生命周期

项目的15个工具并非随意堆砌，而是精心设计以覆盖一个专业自由职业者的完整工作流闭环。我们可以将其分为四个阶段：

第一阶段：机会发现与评估（Discovery & Qualification）这是最耗时也最关键的阶段。search_jobs工具提供了超过15个服务器端过滤器，这意味着过滤逻辑在服务器端执行，比在客户端下载所有数据再过滤更高效。get_job_details不仅返回职位描述，还嵌入了“客户情报”，如客户历史雇佣记录、平均付费、反馈评分等。score_opportunity工具则是智能核心，它综合客户质量、预算匹配度、竞争激烈度和技能匹配度，输出一个0-100的量化评分，并附带红/黄/绿标识的风险提示，帮助AI（和你）快速决策。

第二阶段：提案与竞争分析（Proposal & Competition）在决定投递前，get_connects_balance让你清楚“弹药”还剩多少。search_freelancers则是一个强大的竞争分析工具，你可以按技能、费率、JSS（Job Success Score，Upwork的成功分数）和国家筛选其他自由职业者，了解市场行情和定价策略。

第三阶段：工作管理与财务（Work Management & Finance）成功接单后，track_proposals、list_contracts和get_contract_details帮你管理进行中的项目和合同。manage_milestones允许通过API创建、编辑或请求批准里程碑，这对于固定价格项目自动化至关重要。get_earnings_report则方便你生成收入报告，用于财务统计。

第四阶段：沟通与通知（Communication & Notification）list_messages、send_message和poll_notifications构成了沟通模块。特别是poll_notifications，它采用有状态的差异对比，只返回新消息、提案状态更新或新匹配的职位，避免了重复通知，是实现实时提醒的关键。

注意：这种工具划分方式，使得你可以根据需求灵活组合。例如，你可以构建一个只做“智能机会筛选”的轻量级流程，也可以构建一个从发现到沟通的全自动工作流。

2.3 技术栈选型与架构权衡

项目采用TypeScript构建，这是一个非常务实的选择。TypeScript的强类型系统对于处理像Upwork API返回的复杂嵌套数据结构至关重要，能在编译阶段捕获大量潜在的错误，提升代码的健壮性和可维护性。

在API交互层，项目同时使用了Upwork的GraphQL API和传统的REST API，并以GraphQL为主。这是一个高性能的设计决策。GraphQL允许客户端（在这里是MCP服务器）精确地指定需要哪些字段，一次请求即可获取嵌套关联的所有数据，避免了REST API常见的“N+1”查询问题（即先获取列表，再为每一项获取详情）。例如，在获取职位详情时，很可能需要同时拿到客户信息、技能标签、预算详情等，一个精心设计的GraphQL查询可以一次性搞定，极大提升了效率并减少了网络请求次数。

然而，并非所有Upwork功能都提供了GraphQL端点，因此项目保留了必要的REST调用作为后备（fallback），这体现了工程上的灵活性——在追求最优方案的同时，保证功能的完整性。

架构上，代码组织清晰，分离了关注点：

• auth/目录处理OAuth 2.0授权流和令牌的持久化存储（存在用户本地目录~/.upwork-mcp/下），确保了认证信息的安全与自动刷新。
• common/api-client.ts是核心枢纽，封装了所有对Upwork API的调用，并统一集成了速率限制和错误处理逻辑。
• common/rate-limiter.ts实现了令牌桶算法（10次/秒，300次/分钟，40000次/天），这是遵守Upwork API使用条款、防止账号因请求过快被封禁的关键组件。
• operations/目录下的每个文件对应一个高层次的MCP工具实现，它们调用底层的GraphQL或REST客户端，并将结果格式化为MCP标准响应。

3. 从零开始的详细部署与配置指南

3.1 环境准备与前置条件

在运行任何代码之前，你需要准备好两个核心条件：本地开发环境和Upwork开发者凭证。

首先，确保你的系统安装了Node.js 18或更高版本。你可以通过在终端运行node --version来检查。如果未安装，建议从Node.js官网下载LTS（长期支持）版本进行安装。

其次，也是最重要的一步，是获取Upwork API凭证。这需要你有一个Upwork自由职业者或客户账号。

1. 访问 Upwork开发者门户 。
2. 点击“Apply for API Key”。你需要填写一份申请，说明你使用API的目的（例如，“开发个人工具以自动化管理我的自由职业工作，提高找项目和沟通的效率”）。描述尽量具体、诚实，通过率会更高。
3. 申请通过后，你将在开发者控制台获得一对Client ID和Client Secret。请像保护密码一样保护它们，特别是Client Secret，绝不能提交到公开的代码仓库。

3.2 项目安装与初始配置

获取代码和安装依赖的过程是标准的：

# 克隆项目仓库到本地 git clone https://github.com/AbbottDevelopments/upwork-mcp-server.git # 进入项目目录 cd upwork-mcp-server # 安装所有依赖包（包括TypeScript编译器等） npm install

接下来是配置环节。项目提供了一个环境变量模板文件.env.example。你需要复制它并填入你的凭证：

# 复制模板文件 cp .env.example .env

然后，用文本编辑器打开新创建的.env文件。你会看到类似以下内容：

UPWORK_CLIENT_ID=your_client_id_here UPWORK_CLIENT_SECRET=your_client_secret_here # 可选：设置令牌存储路径，默认在用户主目录下 # UPWORK_TOKEN_STORE_PATH=/custom/path/.upwork-mcp

将your_client_id_here和your_client_secret_here替换为你从Upwork开发者门户获取的真实值。其他配置项通常保持默认即可。

3.3 OAuth 2.0 授权流程详解与首次认证

这是连接Upwork API的关键一步。MCP服务器使用OAuth 2.0授权码流程（Authorization Code Flow），这是一种安全的标准流程，允许用户（你）授权应用程序（MCP服务器）在不需要知道你的Upwork密码的情况下，访问你的Upwork数据。

运行授权命令：

npm run auth

这个过程会发生什么？

1. 脚本启动一个本地HTTP服务器（通常在http://localhost:3000或类似端口）。
2. 自动打开你的默认浏览器，跳转到Upwork的官方授权页面。
3. 你需要用你的Upwork账号登录（如果尚未登录），并看到一个请求权限的页面，询问你是否授权该应用访问你的个人资料、工作信息等。
4. 点击“允许”（Authorize）后，Upwork会将浏览器重定向回你本地的服务器地址，并附上一个一次性的“授权码”。
5. 本地服务器捕获这个授权码，并在后台用它向Upwork交换一个“访问令牌”（Access Token）和一个“刷新令牌”（Refresh Token）。
6. 这些令牌会被安全地加密并存储在你本地机器的~/.upwork-mcp/目录下。刷新令牌的存在至关重要，它使得MCP服务器在访问令牌过期后（通常是2小时），可以自动获取新的访问令牌，而无需你再次手动进行浏览器授权。

实操心得：首次运行npm run auth时，请确保没有其他程序占用常见的端口（如3000）。如果遇到端口冲突，你可以通过修改源代码中auth/oauth.ts里的redirectPort配置来解决。另外，整个授权过程必须在图形化界面的环境下完成，因为需要浏览器交互。对于无界面的服务器环境，需要配置更复杂的OAuth流程，这超出了本项目开箱即用的范围。

3.4 构建与运行服务器

授权成功后，你就可以编译并启动MCP服务器了：

# 将TypeScript源代码编译成JavaScript npm run build # 启动服务器 npm start

如果一切顺利，你会在终端看到服务器已启动的日志，并开始监听来自MCP客户端的连接。此时，服务器本身已经就绪，但它还没有“大脑”——它需要等待一个像Claude Desktop这样的MCP客户端来告诉它具体要做什么。

4. 与AI客户端深度集成：以Claude Desktop为例

4.1 配置Claude Desktop连接

要让Claude AI能够使用这个服务器，你需要修改Claude Desktop的配置文件。这个文件的位置因操作系统而异：

• macOS:~/Library/Application Support/Claude/claude_desktop_config.json
• Windows:%APPDATA%\Claude\claude_desktop_config.json
• Linux:~/.config/Claude/claude_desktop_config.json

如果文件不存在，你可以手动创建它。你需要添加一个mcpServers配置块，指向你刚刚构建好的服务器入口文件：

{ "mcpServers": { "upwork": { "command": "node", "args": ["/absolute/path/to/upwork-mcp-server/dist/index.js"], "env": { "UPWORK_CLIENT_ID": "your-client-id", "UPWORK_CLIENT_SECRET": "your-client-secret" } } } }

关键点解析：

• command: 指定运行环境的命令，这里是node。
• args: 传递给node命令的参数，即编译后的入口文件路径。务必使用绝对路径，相对路径可能导致Claude Desktop找不到文件。
• env: 这里设置的环境变量会传递给服务器进程。虽然我们在.env文件里已经配置过，但在这里再次配置可以确保Claude Desktop启动服务器时能读到这些值。这是一种双保险。

配置完成后，完全重启Claude Desktop应用程序。重启后，Claude应该能连接到你的Upwork MCP服务器。你可以在Claude的输入框里尝试说：“你能用Upwork工具帮我搜索一下最近24小时内发布的、关于Python数据分析和预算高于50美元的职位吗？” 如果配置正确，Claude会调用search_jobs工具并返回结果。

4.2 通过Claude Code命令行集成

对于更喜欢命令行操作或使用Claude Code编辑器的开发者，项目也提供了直接的命令行集成方式：

claude mcp add upwork -- node /absolute/path/to/upwork-mcp-server/dist/index.js

这条命令会向Claude Code的MCP配置中注册名为upwork的服务器。之后，在Claude Code的会话中，你就可以直接使用相关的工具了。这种方式更适合将AI能力集成到开发工作流中。

4.3 工具调用实战：构建一个智能筛选工作流

配置好连接后，真正的威力在于如何通过自然语言指挥AI使用这些工具。下面是一个模拟的、复杂的多步交互场景，展示了如何将多个工具串联起来：

你（对Claude说）：“我想找一个新的数据可视化项目。请帮我搜索过去3天发布的，需要Tableau或Power BI技能，且客户预算在100美元以上的职位。先给我看5个最相关的。”

Claude内部调用search_jobs工具，设置skills: [“Tableau”, “Power BI”],budget_min: 100,posted_date: “3 days”等参数，并返回一个列表。

Claude（回复你）：“找到了8个相关职位。其中前5个是：1. ‘构建销售仪表板’ (预算$150)， 2. ‘财务数据可视化分析’ (预算$500) ... 第2个职位预算较高，你想让我获取它的详细信息并分析一下客户情况吗？”

你：“好的，分析一下第二个职位‘财务数据可视化分析’的详情和客户背景。”

Claude内部依次调用get_job_details获取职位完整描述和客户信息，然后可能调用analyze_client或直接利用get_job_details返回的客户情报进行分析。

Claude：“已获取详情。该客户是一家成立5年的金融科技公司，在Upwork上有42条历史雇佣记录，平均评分4.9/5.0，总支出超过$85k。职位描述清晰，要求提供过往案例。这是一个高质量客户。需要我进一步用score_opportunity工具为这个职位打个综合分吗？”

你：“打一下分，另外再看看有没有其他技能类似的自由职业者在竞争，他们的费率大概是多少？”

Claude内部调用score_opportunity（可能会返回一个85/100的高分，绿色标识），同时调用search_freelancers，设置技能为[“Tableau”, “Power BI”, “Financial analysis”]，查看其他自由职业者的公开费率和JSS。

Claude：“综合评分85/100（绿色），客户质量和预算匹配度都很高。竞争分析显示，有15位技能匹配的自由职业者，他们的平均时薪在$65-$120之间，中位数约$85。你的费率在这个范围内有竞争力。你目前还有足够的Connects来提交提案吗？我可以帮你查一下。”

通过这样的对话，你无需切换浏览器和多个标签页，在一个聊天界面内就完成了搜索、深度分析、竞争调研和投递准备的所有前置工作。AI充当了一个不知疲倦的研究助理和数据分析师。

5. 高级功能与自定义开发指南

5.1 理解速率限制与错误处理机制

作为一个与生产环境API交互的工具，稳健性至关重要。项目的rate-limiter.ts实现了令牌桶算法。简单比喻：你有一个桶，最多能装300个令牌（对应每分钟限额），每秒钟会自动往桶里放入10个新令牌（对应每秒限额）。每次发起一个API请求，就需要从桶里取出一个令牌。如果桶空了，请求就必须等待（或按照策略进行退避），直到有新的令牌放入。

在代码中，当请求被限流时，客户端会抛出结构化的错误，并包含retryable: true的标志和建议的重试等待时间。服务器工具的实现里应该捕获这类错误，并采取指数退避策略进行重试，即第一次等待1秒，第二次等待2秒，第三次等待4秒……以此避免在API暂时性故障时雪崩式地重试。

所有错误都被定义在common/errors.ts中，分为几大类：认证错误、API错误、网络错误、配置错误等。这种结构化的错误处理，使得在构建更复杂的AI工作流时，AI能够根据错误类型做出不同的决策，例如遇到令牌过期错误就尝试刷新令牌，遇到“职位不存在”错误就放弃并报告用户。

5.2 状态轮询与实时通知的实现

poll_notifications工具是实现“实时”感的关键。它不是一个简单的“获取所有新消息”的调用，而是实现了有状态的差异对比。

其原理是：工具内部维护一个“上一次检查的状态快照”（存储在poll-store.ts中）。每次调用poll_notifications时，它实际上会调用Upwork API获取当前的消息列表、提案状态等。然后，将当前状态与上一次存储的状态进行比较，只返回那些发生变化的部分，例如：

• 上次检查后新收到的消息。
• 某个提案的状态从Submitted变成了Viewed或Archived。
• 出现了新的职位匹配推荐。

这种设计非常高效，避免了每次轮询都返回大量重复数据，也让AI的响应更加精准，可以直接告诉你：“你有2条新消息来自客户X”，“你的提案Y被客户查看了”。

5.3 扩展与二次开发：添加自定义工具

开源项目的魅力在于可以按需定制。假设你觉得现有的score_opportunity评分模型不符合你的个人偏好（比如你更看重短期项目，而原模型更看重长期客户），你可以修改或添加新的工具。

例如，你想添加一个calculate_my_effective_rate工具，用于计算你某个合同的实际时薪（总金额除以总记录工时）。你可以按照以下步骤进行：

1. 在src/operations/目录下创建新文件，例如calculate-effective-rate.ts。
2. 定义工具：使用MCP的SDK（本项目应已依赖@modelcontextprotocol/sdk）定义一个名为calculate_my_effective_rate的新工具，它可能需要一个contract_id作为输入参数。
3. 实现逻辑：在工具处理函数中，调用已有的get_contract_details工具（或直接调用底层API客户端）获取合同的总金额和工时记录，然后进行计算。
4. 注册工具：在src/index.ts的主服务器初始化部分，导入并注册你这个新工具。
5. 重新构建：运行npm run build编译TypeScript。
6. 测试：重启服务器，在Claude中尝试调用你的新工具。

项目的模块化结构（分离了operations/工具层和common/api-client.ts基础层）使得这种扩展变得相对清晰和安全。

6. 常见问题、故障排查与安全实践

6.1 安装与配置问题排查表

6.2 安全使用须知与最佳实践

1. 凭证安全是第一要务：你的UPWORK_CLIENT_SECRET等同于密码。绝对不要将它提交到GitHub等公开代码仓库。.env文件已被项目.gitignore排除，请确保你不会意外提交它。在Claude Desktop配置中，虽然可以设置env，但如果你在多用户环境下使用电脑，需注意配置文件可能被其他用户读取的风险。
2. 理解API使用限制：严格遵守Upwork API的速率限制。本项目内置的限流器是为了防止你意外触发限制，但你仍应避免编写疯狂循环调用工具的AI提示。过度调用不仅可能导致你的API访问被临时封禁，也可能违反Upwork平台的使用条款。
3. AI的权限与监督：授权给MCP服务器的权限是广泛的（读取你的个人信息、工作信息、发送消息等）。虽然通过Claude这样的主流AI客户端操作相对安全，但仍建议不要将完全自动化的、无人监督的决策权交给AI。例如，可以让AI筛选和起草提案，但最终点击“发送”前应由你本人审核。特别是涉及金钱的manage_milestones（管理里程碑）操作，务必谨慎。
4. 数据缓存与隐私：MCP服务器本身可能会在本地存储一些状态信息（如轮询状态）。虽然这些数据通常只存在于你的个人电脑上，但如果你在公共或共享电脑上使用，使用完毕后应考虑清理~/.upwork-mcp/目录下的数据。

6.3 性能优化与高级调试

• 开发模式与热重载：在开发自定义工具或修改逻辑时，使用npm run dev命令。它会在watch模式下运行，当你修改src/目录下的.ts文件时，会自动重新编译和重启服务器，无需手动停止和重启。
• 日志与调试：服务器运行时默认会输出一些信息日志。如果需要更详细的调试信息来排查API请求或响应问题，你可以设置环境变量DEBUG=*（或更具体的命名空间）来启用调试输出。具体支持的调试标签需要查看项目代码中是否使用了debug库。
• 处理API变更：Upwork的API（特别是GraphQL接口）可能会更新。如果某个工具突然开始报错，提示字段不存在或查询失败，首先应检查Upwork的官方API文档是否有变动。开源项目可能滞后于官方更新，此时你可能需要根据错误信息，到src/graphql/queries.ts或mutations.ts中调整对应的GraphQL查询语句。

这个项目将一个复杂的平台API封装成了一组AI友好的、功能强大的工具，为自由职业者的效率提升打开了新的可能性。从我个人的使用体验来看，最大的价值不在于全自动化，而在于将我从信息筛选和整理的重复性劳动中解放出来，让我能更专注于策略思考和核心的客户沟通。开始使用时，建议从简单的search_jobs和score_opportunity工具入手，熟悉AI与工具的协作模式，再逐步尝试更复杂的工作流集成。