12.6 · MCP 客户端集成示例（MCP Client Integration Examples）

MCP 客户端集成示例（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/topoteretes/cognee/12.6-mcp-client-integration-examples

翻译时间：2026-05-27T08:45:24.660Z

翻译模型：deepseek-chat

原文字符数：12579

项目：Cognee (cognee)

---

MCP 客户端集成示例

相关源文件

以下文件被用作生成此 Wiki 页面的上下文：

• .github/actions/install_cognee/action.yml
• .github/workflows/cli_tests.yml
• .github/workflows/dockerhub-mcp.yml
• .github/workflows/test_mcp.yml
• Dockerfile
• cognee-mcp/Dockerfile
• cognee-mcp/README.md
• cognee-mcp/entrypoint.sh
• cognee-mcp/pyproject.toml
• cognee-mcp/src/__init__.py
• cognee-mcp/src/client.py
• cognee-mcp/src/cognee_client.py
• cognee-mcp/src/server.py
• cognee-mcp/src/test_client.py
• cognee-mcp/tests/test_mcp_server_hardening.py
• cognee-mcp/uv.lock
• cognee/alembic/versions/7c5d4e2f8a91_add_parent_user_id_to_users.py
• cognee/modules/engine/models/__init__.py
• cognee/modules/tools/__init__.py
• cognee/modules/tools/path_safety.py
• cognee/modules/users/authentication/default/default_transport.py
• cognee/modules/users/authentication/get_api_auth_backend.py
• cognee/modules/users/authentication/get_client_auth_backend.py
• cognee/tests/cli_tests/cli_integration_tests/__init__.py
• cognee/tests/cli_tests/cli_integration_tests/test_cli_integration.py
• cognee/tests/cli_tests/cli_unit_tests/__init__.py
• cognee/tests/cli_tests/cli_unit_tests/test_cli_runner.py
• cognee/tests/unit/test_add_parent_user_id_migration.py
• docker-compose.yml
• entrypoint.sh

本文提供了将 Cognee MCP 服务器与各种 AI 助手客户端集成的实用示例。这些示例涵盖了不同的传输模式（stdio、SSE、HTTP）、连接模式（直接模式、API 模式）以及部署方式（本地、Docker）。

有关 MCP 服务器架构和可用工具的信息，请参阅 MCP 工具参考。有关部署选项，请参阅 Docker 部署。有关 REST API 集成，请参阅 REST API 服务器。

传输模式与连接架构

Cognee MCP 服务器支持三种传输协议和两种连接模式，可以灵活地与不同的客户端环境集成。

传输协议选项

传输模式通过命令行参数 --transport 或环境变量 TRANSPORT_MODE 进行配置 cognee-mcp/src/server.py:4-5，cognee-mcp/entrypoint.sh:45-57。

标题：MCP 传输与连接架构

graph TB
    subgraph "MCP 传输模式"
        STDIO["stdio 传输<br/>（stdin/stdout 管道）"]
        SSE["SSE 传输<br/>（服务器发送事件）"]
        HTTP["HTTP 传输<br/>（可流式 HTTP）"]
    end

    subgraph "连接模式"
        DIRECT["直接模式<br/>cognee 库导入"]
        API["API 模式<br/>HTTP 客户端连接 cognee API"]
    end

    subgraph "客户端"
        CLAUDE_CLI["Claude CLI"]
        CLAUDE_DESKTOP["Claude Desktop"]
        CURSOR["Cursor IDE"]
        VSCODE["VS Code + Cline"]
    end

    STDIO --> CLAUDE_CLI
    STDIO --> DIRECT
    SSE --> CLAUDE_CLI
    SSE --> CLAUDE_DESKTOP
    SSE --> DIRECT
    SSE --> API
    HTTP --> CURSOR
    HTTP --> VSCODE
    HTTP --> DIRECT
    HTTP --> API

    DIRECT --> COGNEE_LIB["cognee 库"]
    API --> COGNEE_API["cognee FastAPI 服务器"]

传输模式	使用场景	端口	协议
stdio	本地 CLI 集成，经典管道通信	不适用	stdin/stdout
sse	实时流式传输，Claude Desktop/CLI	8000	基于 HTTP 的服务器发送事件
http	Web 部署，Cursor，VS Code	8000	支持 CORS 的可流式 HTTP

来源：cognee-mcp/README.md:40-47，cognee-mcp/src/server.py:166-202，cognee-mcp/entrypoint.sh:44-57

连接模式架构

连接模式由 CogneeClient 类处理 cognee-mcp/src/cognee_client.py:31，该类充当 MCP 工具与底层知识引擎之间的桥梁。

标题：CogneeClient 连接逻辑

graph TB
    subgraph "直接模式（CogneeClient.use_api = False）"
        MCP_DIRECT["cognee-mcp 服务器"]
        CLIENT_D["CogneeClient"]
        IMPORT["import cognee"]
        ENG_D["cognee.modules.engine"]

        MCP_DIRECT --> CLIENT_D
        CLIENT_D --> IMPORT
        IMPORT --> ENG_D
    end

    subgraph "API 模式（CogneeClient.use_api = True）"
        MCP_API["cognee-mcp 服务器<br/>--api-url 标志"]
        CLIENT_A["CogneeClient"]
        HTTP_CLIENT["httpx.AsyncClient"]
        COGNEE_API["cognee FastAPI<br/>/api/v1/add<br/>/api/v1/cognify"]

        MCP_API --> CLIENT_A
        CLIENT_A --> HTTP_CLIENT
        HTTP_CLIENT --> COGNEE_API
    end

连接模式由构造函数中的 api_url 参数决定 cognee-mcp/src/cognee_client.py:44-47：

• 直接模式：未指定 api_url，直接导入 cognee 库 cognee-mcp/src/cognee_client.py:65-68。
• API 模式：指定了 api_url，初始化 httpx.AsyncClient 用于远程通信 cognee-mcp/src/cognee_client.py:58-62。

来源：cognee-mcp/src/cognee_client.py:31-68，cognee-mcp/src/server.py:77-78，cognee-mcp/entrypoint.sh:63-89

Claude 桌面集成

使用直接模式的 stdio 传输

最简单的集成方式是使用 stdio 传输，让 Claude Desktop 将 MCP 服务器作为子进程运行。

配置文件： ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）

{
  "mcpServers": {
    "Cognee": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/cognee/cognee-mcp",
        "run",
        "cognee-mcp"
      ],
      "env": {
        "LLM_API_KEY": "your-api-key-here"
      }
    }
  }
}

来源：cognee-mcp/pyproject.toml:70-73，cognee-mcp/README.md:290-307

使用 SSE 传输与 Claude CLI

为了获得流式响应和更好的错误处理，可以使用 SSE 传输。server.py 中的 run_sse_with_cors 函数 cognee-mcp/src/server.py:166-184 负责处理 Uvicorn 的启动设置。

# 使用 SSE 传输启动 MCP 服务器
cd cognee/cognee-mcp
source .venv/bin/activate
python src/server.py --transport sse --host 127.0.0.1 --port 8000

来源：cognee-mcp/src/server.py:166-184，cognee-mcp/README.md:86-89

Cursor IDE 集成

Cursor 需要 HTTP 传输来进行 MCP 集成。该集成依赖于在 run_http_with_cors cognee-mcp/src/server.py:187-202 中配置的 mcp.streamable_http_app()。

HTTP 传输集成流程

标题：通过 HTTP 的工具执行流程

sequenceDiagram
    participant Cursor as "Cursor IDE"
    participant MCP as "cognee-mcp<br/>（FastMCP）"
    participant Client as "CogneeClient"
    participant Cognee as "cognee.cognify()"

    Cursor->>MCP: HTTP POST /mcp<br/>call_tool("cognify")
    MCP->>Client: cognify(datasets)
    Client->>Cognee: await self.cognee.cognify()
    Cognee-->>Client: 成功
    Client-->>MCP: 结果字典
    MCP-->>Cursor: JSON 工具结果

来源：cognee-mcp/src/server.py:187-202，cognee-mcp/src/cognee_client.py:150-198

直接模式配置

Cursor 设置文件： .cursor/mcp.json 或 ~/.cursor/mcp.json

{
  "mcpServers": {
    "Cognee": {
      "url": "http://localhost:8000/mcp",
      "transport": "http"
    }
  }
}

启动服务器：

cd cognee/cognee-mcp
source .venv/bin/activate
python src/server.py --transport http --host 127.0.0.1 --port 8000 --path /mcp

来源：cognee-mcp/README.md:90-93，cognee-mcp/src/server.py:187-202

使用 Cline 扩展的 VS 代码

通过 Cline 扩展集成的 VS Code 使用与 Cursor 类似的 HTTP 传输。

Cline 配置

Cline 设置文件： .vscode/cline_mcp_settings.json

{
  "mcpServers": {
    "Cognee": {
      "url": "http://localhost:8000/mcp",
      "transport": "http",
      "disabled": false
    }
  }
}

启动服务器：

cd cognee/cognee-mcp
uv run python src/server.py --transport http --host 127.0.0.1 --port 8000 --path /mcp

来源：cognee-mcp/README.md:327-344

CORS 配置

HTTP 和 SSE 传输包含用于前端兼容性的 CORS 中间件，通过 _get_cors_origins cognee-mcp/src/server.py:160-163 进行配置，该函数从 MCP_CORS_ALLOW_ORIGINS 读取设置。

来源：cognee-mcp/src/server.py:160-175

基于 Docker 的集成

Docker 部署简化了环境设置。cognee-mcp 中的 entrypoint.sh 脚本负责处理额外依赖的动态安装和传输配置。

Docker 部署架构

标题：Docker MCP 运行时环境

graph TB
    subgraph "Docker 容器"
        ENTRY["entrypoint.sh"]
        SRV["src/server.py"]
        CLI["CogneeClient"]
        VENV[".venv/bin/cognee-mcp"]
    end

    subgraph "主机系统"
        IDE["Cursor/VS Code"]
        ENV[".env 文件"]
    end

    IDE -- "HTTP/SSE" --> SRV
    SRV --> CLI
    ENTRY --> VENV
    VENV --> SRV
    ENV -- "挂载" --> ENTRY

来源：cognee-mcp/Dockerfile:12-94，cognee-mcp/entrypoint.sh:1-102

运行时依赖安装

Docker 容器允许在运行时使用 EXTRAS 环境变量安装可选的依赖组 cognee-mcp/entrypoint.sh:7-40。

# 在运行时安装 postgres 和 neo4j 支持
docker run \
  -e TRANSPORT_MODE=sse \
  -e EXTRAS=postgres,neo4j \
  --env-file ./.env \
  -p 8000:8000 \
  --rm -it cognee/cognee-mcp:main

来源：cognee-mcp/entrypoint.sh:6-40，cognee-mcp/README.md:120-139

环境变量配置参考

传输与连接配置

变量	值	默认值	描述
TRANSPORT_MODE	stdio，sse，http	stdio	MCP 传输协议 cognee-mcp/entrypoint.sh:45
API_URL	URL 字符串	无	Cognee API 服务器 URL（启用 API 模式）cognee-mcp/entrypoint.sh:63
API_TOKEN	令牌字符串	无	API 模式的认证令牌 cognee-mcp/entrypoint.sh:84-85
HTTP_PORT	整数	8000	HTTP/SSE 服务器端口 cognee-mcp/entrypoint.sh:51
MCP_DISABLE_DNS_REBINDING_PROTECTION	true，false	false	禁用主机/来源校验 cognee-mcp/src/server.py:119

来源：cognee-mcp/src/server.py:106-153，cognee-mcp/entrypoint.sh:44-89

数据库配置（传递给 Cognee）

变量	值	默认值	描述
DB_PROVIDER	sqlite，postgres	sqlite	关系型数据库提供者
DB_HOST	主机名	host.docker.internal	数据库主机

来源：docker-compose.yml:61-63

常见集成问题排查

后台任务监控

MCP 服务器为每个数据集维护一个任务错误的环形缓冲区，以帮助调试像 cognify 这样的长时间运行操作 cognee-mcp/src/server.py:79-82。可以通过 cognify_status 工具检索这些信息。

来源：cognee-mcp/src/server.py:79-103

Docker API 模式下的本地主机连接

当在 Docker 中运行 MCP 并连接到主机上的 API 时，localhost 指向的是容器本身。entrypoint.sh 会自动将其转换为 host.docker.internal cognee-mcp/entrypoint.sh:72。

来源：cognee-mcp/entrypoint.sh:66-81