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

MCP 服务端配置

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 客户端和服务器之间如何交换消息。

传输模式架构

来源：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 服务器。

连接模式架构

来源：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

环境变量参考

运行时依赖安装

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 重新绑定保护实现

来源：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 提供配置。

来源：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