CrewAI Tools 实战指南内置工具、自定义工具与 MCP 服务器接入【免费下载链接】crewAIFramework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.项目地址: https://gitcode.com/GitHub_Trending/cr/crewAICrewAI Toolscrewai-tools包是 CrewAI 框架的官方工具集负责为 Agent 提供读写文件、爬取网页、查询数据库/向量库以及调用第三方 API 等扩展能力。本文基于仓库中的 lib/crewai-tools/README.md 展开覆盖其内置工具清单、两种自定义工具的写法继承BaseTool与tool装饰器、MCPModel Context Protocol服务器的两种接入方式并结合源码剖析MCPServerAdapter、BaseTool的参数结构与 MCP 工具适配机制读完你可以直接在自己的 CrewAI 项目中组装、定制工具并把社区 MCP 服务器的工具 1:1 映射为 CrewAI 工具。一、CrewAI Tools 的定位crewai-tools是一个独立的 Python 包元数据定义在 lib/crewai-tools/pyproject.toml包名crewai-tools描述为 Set of tools for the crewAI frameworkPython 版本要求3.10, 3.14核心依赖锁定了crewai1.15.18并内置requests、beautifulsoup4、python-docx、pymupdf、youtube-transcript-api、tiktoken、pytube等基础库其余能力Selenium、Tavily、Snowflake、Qdrant、MCP、Stagehand、MySQL、MongoDB 等全部以optional-dependenciesextras形式提供按需安装、互不干扰。这意味着你只需安装与所用工具匹配的 extra即可避免引入大量无关依赖例如pip install crewai-tools[mcp]只装 MCP 相关依赖。二、内置工具清单官方 README 将内置工具分为六大类见 README 的 Available Tools 一节类别代表工具文件管理File ManagementFileReadTool、FileWriteTool网页抓取Web ScrapingScrapeWebsiteTool、SeleniumScrapingTool数据库集成Database IntegrationsMySQLSearchTool向量数据库集成Vector Database IntegrationsMongoDBVectorSearchTool、QdrantVectorSearchTool、WeaviateVectorSearchToolAPI 集成API IntegrationsSerperApiTool、ExaSearchToolAI 能力工具AI-powered ToolsDallETool、VisionTool、StagehandTool从源码目录lib/crewai-tools/src/crewai_tools/tools/的实际结构看工具规模远超上述清单每个工具都是一个独立子目录如scrape_website_tool/、mysql_search_tool/、exa_tools/、brave_search_tool/、snowflake_search_tool/、youtube_channel_search_tool/、e2b_sandbox_tool/等统一由 lib/crewai-tools/src/crewai_tools/init.py 导出——其中MCPServerAdapter、FileReadTool、ScrapeWebsiteTool均在该文件的__all__中显式列出因此可以直接from crewai_tools import ScrapeWebsiteTool使用。一个内置工具的源码细节ScrapeWebsiteTool以 README 中列出的ScrapeWebsiteTool为例其完整实现在 scrape_website_tool.py可以看清内置工具的典型结构输入参数通过 Pydantic 模型ScrapeWebsiteToolSchema声明其中website_url为必填字段工具本身还暴露website_url可固定某个站点、cookies支持从环境变量取 cookie 值、headers默认携带浏览器 User-Agent 等请求头三个可配置项若构造时传入了固定website_url工具会自动改写description并把参数模式切换为无参的FixedScrapeWebsiteToolSchema——即工具化固定行为 自动更新对 LLM 的说明这一模式网络请求经由crewai_tools.security.safe_requests.safe_get见 safe_requests.py发出并附带 15 秒超时同目录下还有safe_path.py、ssrf_adapter.py说明内置文件/网络类工具带有统一的安全防护层如 SSRF 防护。理解这一结构后你可以按同样的方式阅读FileReadTool、MySQLSearchTool等任意内置工具的参数定义与默认值。三、创建自定义工具两种方式官方 README 给出了两条创建自定义工具的路径两者最终都落在 CrewAI 核心的BaseTool抽象上实现见 lib/crewai/src/crewai/tools/base_tool.py。方式 1子类化BaseTool适合需要复杂状态、多参数、环境变量声明或结果 schema 的场景from crewai.tools import BaseTool class MyCustomTool(BaseTool): name: str Tool Name description: str Detailed description here. def _run(self, *args, **kwargs): # Your tool logic here结合BaseTool的字段定义base_tool.py#L139-L158你在子类中可用到的核心声明项有name工具唯一名称应清晰传达用途Agent 据此选择工具description告诉模型何时/为何/如何使用该工具的说明直接影响工具被选中的概率args_schema: type[BaseModel]工具入参的 Pydantic 模型用于生成暴露给 LLM 的参数 schemaresult_schema: type[BaseModel] | None可选的输出 schema声明后框架会将其序列化信息附加进工具描述帮助模型理解返回结构env_vars: list[EnvVar]声明工具所需环境变量名称、描述、是否必填、默认值。_run是工具执行入口返回字符串结果此外BaseTool还提供cache_function控制缓存策略、max_usage_count使用次数上限等能力并在_generate_description中自动把args_schema转成 JSON Schema 拼入最终 description——这也是 MCP 适配工具所复用的同一机制。方式 2tool装饰器轻量函数式工具推荐直接用装饰器from crewai import tool tool(Tool Name) def my_custom_function(input): # Tool logic here return output从源码 base_tool.py#L677-L730 可以看到tool()支持三种调用形态tool无参使用自动以函数名作为工具名tool(name)指定自定义工具名内部会用.join(name.split()).title()生成参数模型类名;tool(result_as_answerTrue)/tool(result_schemaMyModel, max_usage_count5)声明式选项——result_as_answerTrue表示该工具的返回值直接作为 Agent 的最终回答result_schema指定输出模型max_usage_count限制工具最大调用次数None为不限。有两个硬性约束值得注意源码中显式抛ValueError被装饰函数必须有 docstring用作工具描述和必须有类型注解用于生成参数 schema。装饰器会自动遍历函数签名构建args_schema因此参数命名和注解质量直接决定 LLM 能否正确填参。四、CrewAI Tools 与 MCP接入社区 MCP 服务器这是 README 篇幅最重的部分CrewAI Tools 支持 Model Context ProtocolMCP可以把社区构建的成百上千个 MCP 服务器中的工具直接接入 CrewAI Agent。前置安装使用前必须先安装mcpextra 依赖pip install crewai-tools[mcp] # or uv add crewai-tools --extra mcp对照 pyproject.toml 的 mcp extra其依赖为mcp1.28.1,2与mcpadapt0.1.9。另外源码中还有一个兜底逻辑若忘记安装而直接构造MCPServerAdapter会交互式提示是否立即安装uv add mcp crewai-tools[mcp]否则抛出带提示信息的ImportError见 mcp_adapter.py#L159-L175。选项 1全托管连接上下文管理器用with语句管理连接生命周期MCP 服务器在后台自动启动/停止你只需使用映射出来的 CrewAI 工具STDIO 服务器from mcp import StdioServerParameters from crewai_tools import MCPServerAdapter serverparams StdioServerParameters( commanduvx, args[--quiet, pubmedmcp0.1.3], env{UV_PYTHON: 3.12, **os.environ}, ) with MCPServerAdapter(serverparams) as tools: # tools is now a list of CrewAI Tools matching 1:1 with the MCP servers tools agent Agent(..., toolstools) task Task(...) crew Crew(..., agents[agent], tasks[task]) crew.kickoff(...)SSE 服务器serverparams {url: http://localhost:8000/sse} with MCPServerAdapter(serverparams) as tools: # tools is now a list of CrewAI Tools matching 1:1 with the MCP servers tools agent Agent(..., toolstools) task Task(...) crew Crew(..., agents[agent], tasks[task]) crew.kickoff(...)选项 2手动管理连接更多控制权需要精细控制时显式实例化MCPServerAdapter并在try ... finally中调用stop()确保连接即使出错也能被正确关闭from mcp import StdioServerParameters from crewai_tools import MCPServerAdapter serverparams StdioServerParameters( commanduvx, args[--quiet, pubmedmcp0.1.3], env{UV_PYTHON: 3.12, **os.environ}, ) try: mcp_server_adapter MCPServerAdapter(serverparams) tools mcp_server_adapter.tools # tools is now a list of CrewAI Tools matching 1:1 with the MCP servers tools agent Agent(..., toolstools) task Task(...) crew Crew(..., agents[agent], tasks[task]) crew.kickoff(...) # ** important ** dont forget to stop the connection finally: mcp_server_adapter.stop()SSE 版本同理将serverparams换成{url: http://localhost:8000/sse}即可。源码级机制剖析结合 mcp_adapter.py 的完整实现README 未展开的几个要点值得了解构造签名MCPServerAdapter(serverparams, *tool_names, connect_timeout30)。除 STDIOStdioServerParameters或 SSEdict参数外还支持按名称过滤工具MCPServerAdapter(..., tool1, tool2)只暴露指定工具以及自定义连接超时默认 30 秒生命周期__init__内部即调用start()通过mcpadapt的MCPAdapt.__enter__建立连接若启动失败会自动执行stop()清理并抛出RuntimeError__enter__直接返回tools__exit__负责断开连接——这解释了为什么上下文管理器模式下with语句里工具已立即可用工具映射每个 MCP 工具由CrewAIToolAdapter.adapt()mcp_adapter.py#L31-L85转换成一个动态生成的BaseTool子类工具名经sanitize_tool_name规范化inputSchema经create_model_from_schema转成 Pydantic 参数模型并由_generate_description()把参数 JSON Schema 拼进 description——即 MCP 工具与 CrewAI 工具的1:1 映射在 schema 层面是完整的返回值处理_run调用 MCP 工具后从结果content中提取文本tools属性若服务器未启动就访问会抛ValueError返回类型为ToolCollection[BaseTool]tool_collection.py——它是list的子类额外支持按名称下标访问tools[search]大小写不敏感和filter_by_names/filter_where过滤。测试佐证上述两种接入方式均有真实端到端测试lib/crewai-tools/tests/adapters/mcp_adapter_test.py 用FastMCP动态生成了带echo_tool/calc_tool的 STDIO 与 SSE 回声服务器分别验证了with上下文管理器语法和try ... finally手动停止语法下工具数量、工具名与调用结果如tools[0].run(texthello) Echo: hello。安全考量与当前限制README 明确列出了以下注意事项生产使用前务必阅读信任问题STDIO 服务器会在本机执行代码务必只接入你信任的 MCP 服务器SSE 并非绝对安全恶意 MCP 服务器仍可能向你的应用注入内容功能范围目前只支持 MCP 服务器的tools原语不支持 prompts、resources 等其他 MCP 原语输出限制按官方文档说明调用结果只返回 MCP 服务器工具的第一个文本输出.content[0].text从源码结构看适配层在结果为单个TextContent时直接返回其text为多个内容项时将所有TextContent文本汇总为一个列表字符串返回因此多输出场景的呈现形式以实际适配代码为准。五、开发者环境安装、测试与静态检查README 的 Developer Quickstart 部分给出的官方流程如下pip install crewai[tools]开发环境下针对lib/crewai-tools/目录安装依赖uv sync运行测试uv run pytest运行静态类型检查uv run pyright安装提交前钩子pre-commit install测试资产位于 lib/crewai-tools/tests/含 60 个测试脚本与 YAML 数据每个内置工具通常都有对应的独立测试文件可作为参数用法的第一手参考。构建系统为hatchling版本号取自 src/crewai_tools/init.py。六、何时选择 CrewAI Tools官方 README 给出的三点选型理由可以归纳为简单且灵活内置工具开箱即用BaseTool/tool又保留了足够的自定义空间快速集成通过 extras 机制可即插即用地接入外部服务、API 与数据库面向生产核心依赖版本锁定、安全模块safe_path、safe_requests、SSRF 防护内置、类型注解完整带py.typed标记配合 pyright 静态检查保证一致性。贡献流程遵循标准开源协作方式Fork 并克隆仓库、创建功能分支git checkout -b feature/my-feature、提交git commit -m Add my feature、推送分支后发起 Pull Request问题反馈可通过社区论坛或仓库 Issue 渠道进行。七、小结crewai-tools包的价值在于三点闭环内置工具覆盖文件、网页、数据库、向量库与第三方 API 等常见场景自定义机制BaseTool子类 tool装饰器让你以最小成本扩展专属能力且两者共享同一套 schema/description 机制MCP 适配层MCPServerAdapterToolCollection则把社区 MCP 生态的工具以 1:1 方式安全地纳入 CrewAI Agent。掌握本文的两种自定义写法和两种 MCP 接入模式后即可在当前仓库的 README、mcp_adapter.py、base_tool.py 与 MCP 测试用例 之间对照源码深入任何你关心的工具实现细节。【免费下载链接】crewAIFramework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.项目地址: https://gitcode.com/GitHub_Trending/cr/crewAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考