关键词

Python SDKLLM工具扩展Claude Code工具内嵌MCP服务器高性能工具集成

项目简介

'claude-agent-sdk-python' 是Anthropic为Python开发者提供的Claude Agent SDK，旨在简化与Claude Code的交互。除了作为客户端调用Claude功能外，它还支持创建“内嵌MCP工具服务器”，让Python函数可以直接作为工具被Claude Code调用，无需独立的MCP服务器进程，实现高性能和便捷集成。

主要功能点

  • 内嵌MCP工具托管: 允许Python函数直接注册为MCP工具，通过SDK在应用内部运行，响应Claude Code的工具调用请求。
  • 高性能通信: 工具调用在同一进程内完成，避免进程间通信（IPC）开销，提升工具执行效率。
  • 简化部署与调试: 无需管理额外的MCP服务器进程，简化应用部署流程，并方便在同一Python环境中进行工具调试。
  • Claude Code交互: 提供丰富的API用于与Claude Code进行对话、发送指令、处理响应等。

安装步骤

  1. Python SDK 安装: 
    pip install claude-agent-sdk
  2. Claude Code CLI 安装: 确保您的系统中已安装 Node.js，然后通过 npm 全局安装 Claude Code CLI（版本 2.0.0 或更高）。这是SDK与内嵌MCP服务器通信所必需的外部客户端。 
    npm install -g @anthropic-ai/claude-code
  3. 配置环境 (可选): 如果Claude Code CLI不在系统PATH中，可以通过 'ClaudeAgentOptions(cli_path='/path/to/claude')' 指定其路径。

服务器配置 (用于MCP客户端，例如Claude Code CLI)

当MCP客户端（例如Claude Code CLI）需要调用您在Python SDK中定义的内嵌MCP工具时，它需要知道如何连接到这些工具。您无需编写JSON-RPC服务器代码，SDK已为您处理。MCP客户端在启动时通过'--mcp-config'参数接收配置，告知其有哪些MCP服务器可用。

例如，以下JSON配置代表一个名为"calculator"的内嵌MCP服务器，其中包含'add'、'subtract'等工具。Claude Code CLI会通过SDK的内部机制与这个内嵌服务器通信，而不是直接启动一个外部进程。

{
  "mcpServers": {
    "calculator": {
      "type": "sdk",
      "name": "calculator",
      "version": "2.0.0"
    }
  }
}
  • 'calculator': 服务器的名称，此名称将在MCP客户端中用于引用该工具集（例如，Claude Code会通过 'mcp__calculator__add' 这样的格式来调用 'add' 工具）。
  • 'type: "sdk"': 指明这是一个由Claude Agent SDK for Python托管的内嵌服务器。
  • 'name: "calculator"': 与外部服务器配置中的'name'字段对应，用于标识此MCP服务器。
  • 'version: "2.0.0"': MCP服务器的版本信息。

基本使用方法 (在Python应用中定义并使用MCP工具)

以下示例展示如何在Python应用中定义 'add' 和 'greet' 工具，并将它们注册为内嵌MCP服务器。一旦运行，Claude Code CLI就能通过SDK调用这些工具。

import asyncio
from typing import Any
from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient, create_sdk_mcp_server, tool

# 1. 定义MCP工具
@tool("add", "将两个数字相加", {"a": float, "b": float})
async def add_numbers(args: dict[str, Any]) -> dict[str, Any]:
    result = args["a"] + args["b"]
    return {"content": [{"type": "text", "text": f"{args['a']} + {args['b']} = {result}"}]}

@tool("greet", "问候用户", {"name": str})
async def greet_user(args: dict[str, Any]) -> dict[str, Any]:
    return {"content": [{"type": "text", "text": f"你好，{args['name']}!"}]}

async def main():
    # 2. 创建内嵌MCP服务器
    my_tools_server = create_sdk_mcp_server(
        name="my-tools",
        version="1.0.0",
        tools=[add_numbers, greet_user]
    )

    # 3. 配置Claude Agent Options以使用该服务器
    options = ClaudeAgentOptions(
        mcp_servers={"my-custom-tools": my_tools_server}, # "my-custom-tools"是客户端会使用的服务器别名
        allowed_tools=["mcp__my-custom-tools__add", "mcp__my-custom-tools__greet"], # 允许Claude调用这些工具
        # 其他选项，例如：model="claude-sonnet-4-5"
    )

    # 4. 使用ClaudeSDKClient与Claude Code进行交互
    async with ClaudeSDKClient(options=options) as client:
        print("用户: 计算 10 + 20")
        await client.query("使用add工具计算 10 + 20")
        async for msg in client.receive_response():
            print(msg) # Claude会输出工具调用结果

        print("\n用户: 问候 Bob")
        await client.query("使用greet工具问候 Bob")
        async for msg in client.receive_response():
            print(msg) # Claude会输出工具调用结果

if __name__ == "__main__":
    asyncio.run(main())

信息

分类

开发者工具

访问项目