agentic_huge_data_base / wiki
页面 Cognee · 11.3 MCP 服务端配置·DeepWiki 中文全文译文
DeepWiki 中文译文 / Cognee / 11.3

11.3 · MCP 服务端配置（MCP Server Configuration）

记忆管道与知识图谱构建 · 本章是 Cognee DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Cognee 章节11.3 状态全文译文 模块配置治理、安装与启动、接口与服务契约、认证、权限与安全
项目要点页2.5 参考项目 项目章节目录Cognee DeepWiki 原始章节MCP Server Configuration 上一章11.2 下一章12
源码线索
  • .github/workflows/dockerhub-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
模块标签
  • 配置治理
  • 安装与启动
  • 接口与服务契约
  • 认证、权限与安全
  • 工作流与编排

中文译文

MCP 服务端配置（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/topoteretes/cognee/11.3-mcp-server-configuration
翻译时间：2026-05-27T08:45:27.688Z
翻译模型：deepseek-chat
原文字符数：13621
项目：Cognee (cognee)

--- 好的，作为一名资深技术文档翻译专家，我将严格遵循您的要求，对这份 DeepWiki 技术文档进行全文翻译和润色。

---

MCP 服务器配置

相关源文件

生成此维基页面所使用的上下文文件：

  • .github/workflows/dockerhub-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/uv.lock
  • cognee/alembic/versions/7c5d4e2f8a91_add_parent_user_id_to_users.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/unit/test_add_parent_user_id_migration.py
  • docker-compose.yml
  • entrypoint.sh

本文档记录了 Cognee 的模型上下文协议（MCP）服务器的配置选项。该服务器使 AI 助手（如 Claude、Cursor、VS Code）能够与 Cognee 的知识图谱系统进行交互。MCP 服务器可以在多种传输模式和连接模式下运行，其配置可通过环境变量、命令行参数或客户端配置文件进行管理。

关于 MCP 工具及其用法的信息，请参阅 MCP 工具参考。关于搜索和查询功能的详细信息，请参阅 搜索与查询工具。

---

传输模式

MCP 服务器支持三种与客户端通信的传输协议。传输模式决定了 MCP 客户端和服务器之间如何交换消息。

传输模式架构
graph TB
    subgraph "MCP 客户端"
        ["CLAUDE_CLIENT"]["Claude CLI/桌面版"]
        ["CURSOR_IDE"]["Cursor IDE"]
        ["VSCODE_IDE"]["VS Code + Cline"]
    end

    subgraph "传输层"
        ["STDIO_TRANSPORT"]["stdio 传输<br/>（默认）<br/>标准输入/输出管道"]
        ["SSE_TRANSPORT"]["SSE 传输<br/>服务器推送事件<br/>http://主机:端口/sse"]
        ["HTTP_TRANSPORT"]["HTTP 传输<br/>可流式 HTTP<br/>http://主机:端口/mcp"]
    end

    subgraph "MCP 服务器进程"
        ["FAST_MCP_INSTANCE"]["cognee-mcp/src/server.py<br/>FastMCP 实例"]
        ["ROUTES"]["自定义路由：<br/>/health<br/>/sse<br/>/mcp"]
        ["CORS_MIDDLEWARE"]["CORS 中间件"]
    end

    ["STDIO_TRANSPORT"] --> ["FAST_MCP_INSTANCE"]
    ["SSE_TRANSPORT"] --> ["CORS_MIDDLEWARE"]
    ["HTTP_TRANSPORT"] --> ["CORS_MIDDLEWARE"]
    ["CORS_MIDDLEWARE"] --> ["ROUTES"]
    ["ROUTES"] --> ["FAST_MCP_INSTANCE"]

    ["CLAUDE_CLIENT"] -.stdio.-> ["STDIO_TRANSPORT"]
    ["CLAUDE_CLIENT"] -.sse.-> ["SSE_TRANSPORT"]
    ["CURSOR_IDE"] -.http.-> ["HTTP_TRANSPORT"]
    ["VSCODE_IDE"] -.http.-> ["HTTP_TRANSPORT"]

来源：cognee-mcp/src/server.py:168-196, cognee-mcp/README.md:40-41

stdio 传输（默认）

基于标准输入/输出管道的通信方式。这是用于本地进程的经典 MCP 传输模式。

用法：

# 直接使用 Python
python src/server.py --transport stdio

# 使用 Docker
docker run -e TRANSPORT_MODE=stdio cognee/cognee-mcp:main

特点：

  • 同步请求/响应。
  • 无需网络端口。
  • 最适合本地、单客户端场景。
  • Claude CLI 在管道模式下默认使用此方式。

实现方式： 服务器创建一个 FastMCP 实例 cognee-mcp/src/server.py:73，该实例通过 main 函数中的 mcp.run() 处理 stdio 通信 cognee-mcp/src/server.py:821。

来源：cognee-mcp/src/server.py:73, cognee-mcp/src/server.py:821, cognee-mcp/entrypoint.sh:45-46, cognee-mcp/README.md:82-85

SSE 传输（服务器推送事件）

使用基于 HTTP 的服务器推送事件（SSE）实现的实时流式传输。

用法：

# 直接使用 Python
python src/server.py --transport sse --host 0.0.0.0 --port 8000

# 使用 Docker
docker run -e TRANSPORT_MODE=sse -p 8000:8000 cognee/cognee-mcp:main

特点：

  • 从服务器到客户端的单向流式传输。
  • 需要网络端口（默认：8000）。
  • 包含用于 Web 访问的 CORSMiddleware。
  • 推荐用于 Claude 桌面版。

实现方式： run_sse_with_cors() cognee-mcp/src/server.py:166-185 使用 CORSMiddleware 包装 mcp.sse_app()，其中 CORS 来源由 _get_cors_origins() cognee-mcp/src/server.py:160-163 解析。

来源：cognee-mcp/src/server.py:160-185, cognee-mcp/README.md:86-89, docker-compose.yml:60

HTTP 传输（可流式 HTTP）

用于请求/响应模式的双向 HTTP 传输。

用法：

# 直接使用 Python
python src/server.py --transport http --host 0.0.0.0 --port 8000 --path /mcp

# 使用 Docker
docker run -e TRANSPORT_MODE=http -p 8000:8000 cognee/cognee-mcp:main

特点：

  • 完整的双向 HTTP 通信。
  • 推荐用于 Web 部署。
  • 可配置自定义路径（默认：/mcp）。
  • 包含 CORSMiddleware。

实现方式： run_http_with_cors() cognee-mcp/src/server.py:187-206 使用 CORSMiddleware 包装 mcp.streamable_http_app()。

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

---

连接模式

MCP 服务器可以在两种不同的模式下运行，具体取决于它是直接使用 Cognee 库，还是连接到独立的 API 服务器。

连接模式架构
graph TB
    subgraph "MCP 服务器进程"
        ["SERVER_MAIN_FUNC"]["cognee-mcp/src/server.py:main()"]
        ["COGNEE_CLIENT_CLASS"]["cognee_client.py:CogneeClient"]
        ["API_MODE_CHECK"]{"设置了 api_url？"}
    end

    subgraph "直接模式"
        ["IMPORT_COGNEE_LIB"]["import cognee"]
        ["COGNEE_ADD_CALL"]["cognee.add()"]
        ["COGNEE_COGNIFY_CALL"]["cognee.cognify()"]
        ["COGNEE_SEARCH_CALL"]["cognee.search()"]
    end

    subgraph "API 模式"
        ["HTTPX_ASYNC_CLIENT"]["httpx.AsyncClient"]
        ["API_V1_ENDPOINTS"]["/api/v1/add<br/>/api/v1/cognify<br/>/api/v1/search"]
        ["FASTAPI_SERVER"]["Cognee FastAPI 服务器"]
    end

    subgraph "数据库"
        ["VECTOR_DB_ENGINE"]["VectorDBInterface"]
        ["GRAPH_DB_ENGINE"]["GraphDBInterface"]
        ["SQL_ADAPTER"]["SQLAlchemyAdapter"]
    end

    ["SERVER_MAIN_FUNC"] --> ["API_MODE_CHECK"]
    ["API_MODE_CHECK"] -->|否| ["IMPORT_COGNEE_LIB"]
    ["API_MODE_CHECK"] -->|是| ["HTTPX_ASYNC_CLIENT"]

    ["IMPORT_COGNEE_LIB"] --> ["COGNEE_CLIENT_CLASS"]
    ["COGNEE_CLIENT_CLASS"] --> ["COGNEE_ADD_CALL"]
    ["COGNEE_CLIENT_CLASS"] --> ["COGNEE_COGNIFY_CALL"]
    ["COGNEE_CLIENT_CLASS"] --> ["COGNEE_SEARCH_CALL"]

    ["HTTPX_ASYNC_CLIENT"] --> ["COGNEE_CLIENT_CLASS"]
    ["COGNEE_CLIENT_CLASS"] --> ["API_V1_ENDPOINTS"]
    ["API_V1_ENDPOINTS"] --> ["FASTAPI_SERVER"]

    ["COGNEE_ADD_CALL"] --> ["VECTOR_DB_ENGINE"]
    ["COGNEE_ADD_CALL"] --> ["GRAPH_DB_ENGINE"]
    ["COGNEE_ADD_CALL"] --> ["SQL_ADAPTER"]

    ["FASTAPI_SERVER"] --> ["VECTOR_DB_ENGINE"]
    ["FASTAPI_SERVER"] --> ["GRAPH_DB_ENGINE"]
    ["FASTAPI_SERVER"] --> ["SQL_ADAPTER"]

来源：cognee-mcp/src/server.py:77, cognee-mcp/src/cognee_client.py:31-68, cognee-mcp/entrypoint.sh:62-89

直接模式

在直接模式下，MCP 服务器在同一进程中直接导入并使用 Cognee 库。如果未提供 API URL，则此为默认行为。

配置：

  • 不要设置 API_URL 环境变量。
  • CogneeClient 会导入本地的 cognee 包 cognee-mcp/src/cognee_client.py:68。

实现方式： 当初始化时未提供 api_url，CogneeClient cognee-mcp/src/cognee_client.py:31-68 会将 self.use_api 设置为 False。后续的调用，如 add() cognee-mcp/src/cognee_client.py:147，会使用 await self.cognee.add()。

来源：cognee-mcp/src/cognee_client.py:44-68, cognee-mcp/src/cognee_client.py:147, cognee-mcp/entrypoint.sh:88

API 模式

在 API 模式下，MCP 服务器充当代理，将请求转发到独立的 Cognee FastAPI 服务器（可以是本地、自托管或 Cognee 云服务）。

配置：

# 环境变量
API_URL=http://localhost:8000
API_TOKEN=your_auth_token  # 可选

实现方式： 当提供了 api_url 时，CogneeClient cognee-mcp/src/cognee_client.py:62 会初始化一个 httpx.AsyncClient。API 调用通过 _get_headers() cognee-mcp/src/cognee_client.py:70-85 包含认证请求头，该方法支持 Bearer 令牌以及云服务特定的 X-Api-Key/X-Tenant-Id 请求头。

Docker 中 localhost 的处理： entrypoint.sh 脚本会自动将 API_URL 中的 localhost 或 127.0.0.1 转换为 host.docker.internal，以确保 Docker 环境能够连接到宿主机 cognee-mcp/entrypoint.sh:67-81。

来源：cognee-mcp/src/cognee_client.py:31-85, cognee-mcp/entrypoint.sh:62-83

---

环境变量参考

变量类型默认值描述
TRANSPORT_MODE字符串stdio传输协议：stdio、sse 或 http cognee-mcp/entrypoint.sh:45
API_URL字符串无Cognee API 服务器 URL（启用 API 模式）cognee-mcp/entrypoint.sh:63
API_TOKEN字符串无API 模式的认证令牌 cognee-mcp/entrypoint.sh:84
MCP_DISABLE_DNS_REBINDING_PROTECTION布尔值false禁用 Host/Origin 请求头校验 cognee-mcp/src/server.py:119
MCP_ALLOWED_HOSTS字符串无逗号分隔的 Host 请求头模式 cognee-mcp/src/server.py:128
MCP_CORS_ALLOW_ORIGINS字符串http://localhost:3000CORS 允许的来源 cognee-mcp/src/server.py:162
EXTRAS字符串无逗号分隔的可选依赖项，在运行时安装 cognee-mcp/entrypoint.sh:7
DB_PROVIDER字符串sqlite直接模式下的数据库提供者 docker-compose.yml:62
运行时依赖安装

EXTRAS 环境变量允许在容器启动时动态安装可选的 Cognee 功能（例如 postgres、neo4j 或 aws）cognee-mcp/entrypoint.sh:7-40。

实现方式： 入口点脚本会检测当前的 cognee 版本 cognee-mcp/entrypoint.sh:11，然后针对请求的额外依赖项运行 uv pip install cognee-mcp/entrypoint.sh:33。

来源：cognee-mcp/entrypoint.sh:7-40, cognee-mcp/README.md:120-148

---

传输安全配置

MCP 服务器通过 TransportSecuritySettings 实现了 DNS 重新绑定保护和主机校验，以防止恶意的跨域请求 cognee-mcp/src/server.py:106-153。

DNS 重新绑定保护实现
graph LR
    ["ALLOWED_HOSTS_ENV"]("MCP_ALLOWED_HOSTS")
    ["DISABLE_REBIND_ENV"]("MCP_DISABLE_DNS_REBINDING_PROTECTION")
    ["CONFIG_SECURITY_FUNC"]("server.py: _configure_transport_security()")
    ["TRANSPORT_SEC_SETTINGS"]("TransportSecuritySettings")
    ["MCP_GLOBAL_SETTINGS"]("mcp.settings")

    ["ALLOWED_HOSTS_ENV"] --> ["CONFIG_SECURITY_FUNC"]
    ["DISABLE_REBIND_ENV"] --> ["CONFIG_SECURITY_FUNC"]
    ["CONFIG_SECURITY_FUNC"] --> ["TRANSPORT_SEC_SETTINGS"]
    ["TRANSPORT_SEC_SETTINGS"] --> ["MCP_GLOBAL_SETTINGS"]

来源：cognee-mcp/src/server.py:106-153

实现方式： _configure_transport_security cognee-mcp/src/server.py:106 会填充 mcp.settings.transport_security。如果主机不是回环地址，它会根据环境变量显式设置 allowed_hosts 和 allowed_origins cognee-mcp/src/server.py:141-145。

来源：cognee-mcp/src/server.py:106-153

---

命令行参数

当直接运行 MCP 服务器时，通过 argparse cognee-mcp/src/server.py:775-801 提供配置。

参数简写默认值描述
--transport-tstdiostdio、sse 或 http
--host无127.0.0.1sse/http 的绑定地址
--port-p8000sse/http 的端口
--api-url无无API 模式的 URL
--api-token无无API 模式的令牌
--no-migration无False跳过数据库迁移 cognee-mcp/src/server.py:799

来源：cognee-mcp/src/server.py:775-801

---

Docker 配置

docker-compose.yml 中的 cognee-mcp 服务提供了一个标准的部署配置：

cognee-mcp:
  container_name: cognee-mcp
  profiles:
    - mcp
  environment:
    - TRANSPORT_MODE=sse
    - DB_PROVIDER=${DB_PROVIDER:-sqlite}
    - MCP_LOG_LEVEL=INFO
  ports:
    - "8000:8000"

来源：docker-compose.yml:41-81

MCP 服务器的 Dockerfile 使用多阶段构建：首先使用 Node 构建 UI 包 cognee-mcp/Dockerfile:4-11，然后使用 uv 安装 Python 依赖 cognee-mcp/Dockerfile:13-55，最后生成一个精简的运行时镜像 cognee-mcp/Dockerfile:57-94。

来源：cognee-mcp/Dockerfile:1-94