认知记忆管理平台

cognee‑mcp - 将Cognee记忆引擎作为模型上下文协议服务器运行

GitHub stars

为智能体构建记忆系统，并通过支持MCP协议的任意客户端进行查询——无论是终端还是IDE环境均可使用。

✨ 功能特性

多传输协议支持——可选择流式HTTP（推荐用于Web部署）、SSE（实时流传输）或标准输入输出（默认管道模式）
API模式——连接已运行的Cognee FastAPI服务器而非直接使用cognee（详见下方API模式说明）
集成日志系统——所有操作记录均写入循环日志文件（可通过get_log_file_location()获取路径），开发环境下同时输出到控制台
本地文件摄取——直接读取磁盘上的.md文档、源代码文件、Cursor规则集等
后台处理管道——长时间运行的认知化(cognify)与编码化(codify)任务在子线程执行，可通过状态工具查看进度
开发者规则引导——单次调用即可将.cursorrules、.cursor/rules、AGENT.md等文件索引至developer_rules节点集
清理与重置——当需要全新开始时，通过prune命令一键清空记忆存储

更多详细信息请参阅官方文档。

🚀 快速开始

克隆cognee仓库

git clone https://github.com/topoteretes/cognee.git

进入cognee-mcp子目录
```
cd cognee/cognee-mcp
```
安装uv（如未安装）
```
pip install uv
```
使用uv安装cognee mcp服务器所需依赖
```
uv sync --dev --all-extras --reinstall
```
在cognee mcp目录激活虚拟环境
```
source .venv/bin/activate
```
在.env中设置OpenAI API密钥以使用默认配置快速启动
```
LLM_API_KEY="您的OPENAI_API密钥"
```

以标准输入输出模式运行cognee mcp服务器（默认）

python src/server.py

或通过SSE流式传输响应

python src/server.py --transport sse

或使用流式HTTP传输（推荐Web部署）

python src/server.py --transport http --host 127.0.0.1 --port 8000 --path /mcp

如需高级配置，请使用我们的模板创建.env文件。要使用不同的LLM提供商/数据库配置，请查阅官方文档获取更多信息。

🐳 Docker使用指南

如需在容器中运行cognee-mcp，您有两种选择：

本地构建

确保位于/cognee根目录，且.env文件仅包含LLM_API_KEY（及您选择的配置）。

移除旧镜像并重新构建：

docker rmi cognee/cognee-mcp:main || true
docker build --no-cache -f cognee-mcp/Dockerfile -t cognee/cognee-mcp:main .

运行容器：

# HTTP传输（推荐Web部署）
docker run -e TRANSPORT_MODE=http --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main
# SSE传输
docker run -e TRANSPORT_MODE=sse --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main
# 标准输入输出传输（默认）
docker run -e TRANSPORT_MODE=stdio --env-file ./.env --rm -it cognee/cognee-mcp:main

运行时安装可选依赖：

通过设置EXTRAS环境变量可在运行时安装可选依赖：

# 安装单个可选依赖组
docker run \
  -e TRANSPORT_MODE=http \
  -e EXTRAS=aws \
  --env-file ./.env \
  -p 8000:8000 \
  --rm -it cognee/cognee-mcp:main

# 安装多个可选依赖组（逗号分隔）
docker run \
  -e TRANSPORT_MODE=sse \
  -e EXTRAS=aws,postgres,neo4j \
  --env-file ./.env \
  -p 8000:8000 \
  --rm -it cognee/cognee-mcp:main

可选依赖组列表：

aws - S3存储支持
postgres / postgres-binary - PostgreSQL数据库支持
neo4j - Neo4j图数据库支持
neptune - AWS Neptune支持
chromadb - ChromaDB向量存储支持
scraping - 网页抓取能力
distributed - Modal分布式执行
langchain - LangChain集成
llama-index - LlamaIndex集成
anthropic - Anthropic模型
groq - Groq模型
mistral - Mistral模型
ollama / huggingface - 本地模型支持
docs - 文档处理
codegraph - 代码分析
monitoring - Sentry & Langfuse监控
redis - Redis支持
更多选项（完整列表见pyproject.toml）

从Docker Hub拉取（无需构建）：

# HTTP传输（推荐Web部署）
docker run -e TRANSPORT_MODE=http --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main
# SSE传输
docker run -e TRANSPORT_MODE=sse --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main
# 标准输入输出传输（默认）
docker run -e TRANSPORT_MODE=stdio --env-file ./.env --rm -it cognee/cognee-mcp:main

运行时安装可选依赖：

# 从Docker Hub镜像安装可选依赖
docker run \
  -e TRANSPORT_MODE=http \
  -e EXTRAS=aws,postgres \
  --env-file ./.env \
  -p 8000:8000 \
  --rm -it cognee/cognee-mcp:main

重要提示：Docker与直接使用区别

Docker使用环境变量，而非命令行参数：

✅ Docker正确方式：-e TRANSPORT_MODE=http
❌ Docker错误方式：--transport http（无效）

直接Python使用需用命令行参数：

✅ 直接使用正确方式：python src/server.py --transport http
❌ 直接使用错误方式：-e TRANSPORT_MODE=http（无效）

Docker API模式

将MCP Docker容器连接到主机运行的Cognee API服务器：

简易用法（自动处理localhost）：

# 在主机启动Cognee API服务器
python -m cognee.api.client

# 以API模式运行MCP容器 - localhost会自动转换！
docker run \
  -e TRANSPORT_MODE=sse \
  -e API_URL=http://localhost:8000 \
  -e API_TOKEN=您的认证令牌 \
  -p 8001:8000 \
  --rm -it cognee/cognee-mcp:main

注意： 容器在Mac/Windows/Docker Desktop环境下会自动将localhost转换为host.docker.internal。您将在日志中看到转换提示。

显式使用host.docker.internal（Mac/Windows）：

# 或显式指定host.docker.internal
docker run \
  -e TRANSPORT_MODE=sse \
  -e API_URL=http://host.docker.internal:8000 \
  -e API_TOKEN=您的认证令牌 \
  -p 8001:8000 \
  --rm -it cognee/cognee-mcp:main

Linux系统（使用主机网络或容器IP）：

# 方案1：使用主机网络（最简单）
docker run \
  --network host \
  -e TRANSPORT_MODE=sse \
  -e API_URL=http://localhost:8000 \
  -e API_TOKEN=您的认证令牌 \
  --rm -it cognee/cognee-mcp:main

# 方案2：使用主机IP地址
# 首先获取主机IP：ip addr show docker0
docker run \
  -e TRANSPORT_MODE=sse \
  -e API_URL=http://172.17.0.1:8000 \
  -e API_TOKEN=您的认证令牌 \
  -p 8001:8000 \
  --rm -it cognee/cognee-mcp:main

API模式环境变量说明：

API_URL: 运行的Cognee API服务器URL
API_TOKEN: 认证令牌（可选，当API启用认证时必需）

注意： 在API模式下运行时：

数据库迁移会自动跳过（API服务器自行处理其数据库）
部分功能受限（参见API模式限制）

🔗 MCP客户端配置

使用Docker启动Cognee MCP服务器后，需要配置MCP客户端以连接至服务器。

SSE传输配置（推荐）

以SSE传输模式启动服务器：

docker run -e TRANSPORT_MODE=sse --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main

配置MCP客户端：

Claude CLI（最简单方式）

claude mcp add cognee-sse -t sse http://localhost:8000/sse

验证连接：

claude mcp list

应显示服务器已连接：

检查MCP服务器状态...

cognee-sse: http://localhost:8000/sse (SSE) - ✓ 已连接

手动配置

Claude（~/.claude.json）

{
  "mcpServers": {
    "cognee": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

Cursor（~/.cursor/mcp.json）

{
  "mcpServers": {
    "cognee-sse": {
      "url": "http://localhost:8000/sse"
    }
  }
}

HTTP传输配置（备选方案）

以HTTP传输模式启动服务器：

docker run -e TRANSPORT_MODE=http --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main

配置MCP客户端：

Claude CLI（最简单方式）

claude mcp add cognee-http -t http http://localhost:8000/mcp

验证连接：

claude mcp list

应显示服务器已连接：

检查MCP服务器状态...

cognee-http: http://localhost:8000/mcp (HTTP) - ✓ 已连接

手动配置

Claude（~/.claude.json）

{
  "mcpServers": {
    "cognee": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Cursor（~/.cursor/mcp.json）

{
  "mcpServers": {
    "cognee-http": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

双重配置示例

可同时配置两种传输方式用于测试：

{
  "mcpServers": {
    "cognee-sse": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    },
    "cognee-http": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

注意： 仅启用实际运行的服务器以避免连接错误。

🌐 API模式

MCP服务器可在两种模式下运行：

直连模式（默认）

MCP服务器直接导入并使用cognee库。此为默认模式，支持完整功能。

API模式

MCP服务器通过HTTP请求连接到已运行的Cognee FastAPI服务器。适用于以下场景：

已运行集中式Cognee API服务器
需要将MCP服务器与知识图谱后端分离
需要多个MCP服务器共享同一知识图谱

以API模式启动MCP服务器：

# 首先启动Cognee FastAPI服务器（默认端口8000）
cd /path/to/cognee
python -m cognee.api.client

# 然后以API模式启动MCP服务器
cd cognee-mcp
python src/server.py --api-url http://localhost:8000 --api-token YOUR_AUTH_TOKEN

不同传输协议的API模式：

# 使用SSE传输
python src/server.py --transport sse --api-url http://localhost:8000 --api-token YOUR_TOKEN

# 使用HTTP传输
python src/server.py --transport http --api-url http://localhost:8000 --api-token YOUR_TOKEN

Docker中的API模式：

# Mac/Windows系统（使用host.docker.internal访问宿主机）
docker run \
  -e TRANSPORT_MODE=sse \
  -e API_URL=http://host.docker.internal:8000 \
  -e API_TOKEN=YOUR_TOKEN \
  -p 8001:8000 \
  --rm -it cognee/cognee-mcp:main

# Linux系统（使用宿主机网络）
docker run \
  --network host \
  -e TRANSPORT_MODE=sse \
  -e API_URL=http://localhost:8000 \
  -e API_TOKEN=YOUR_TOKEN \
  --rm -it cognee/cognee-mcp:main

API模式的命令行参数：

--api-url: 运行中的Cognee FastAPI服务器基础URL（如http://localhost:8000）
--api-token: API认证令牌（可选，若API启用认证则必需）

API模式的Docker环境变量：

API_URL: 运行中的Cognee FastAPI服务器基础URL
API_TOKEN: 认证令牌（可选，若API启用认证则必需）

API模式限制： 部分功能仅在直连模式下可用：

codify（代码图谱管道）
cognify_status/codify_status（管道状态跟踪）
prune（数据重置）
get_developer_rules（开发者规则检索）
带特定dataset_id的list_data（详细数据列表）

基础操作如cognify、search、delete和list_data（所有数据集）在两种模式下均可用。

💻 基础使用

MCP服务器通过工具暴露其功能。可从任何MCP客户端（Cursor、Claude Desktop、Cline、Roo等）调用这些工具。

可用工具

cognify: 将数据转化为结构化知识图谱并存储于内存
cognee_add_developer_rules: 将核心开发者规则文件摄入内存
codify: 分析代码仓库，构建代码图谱并存储于内存
delete: 从数据集中删除特定数据（支持软/硬删除模式）
get_developer_rules: 检索基于先前交互生成的所有开发者规则
list_data: 列出所有数据集及其数据项（含删除操作所需的ID）
save_interaction: 记录用户代理交互及查询-回答对
prune: 重置cognee以重新开始（移除所有数据）
search: 查询内存 - 支持GRAPH_COMPLETION、RAG_COMPLETION、CODE、CHUNKS、SUMMARIES、CYPHER和FEELING_LUCKY
cognify_status/codify_status: 跟踪管道进度

数据管理示例：

# 列出所有可用数据集及数据项
list_data()

# 列出特定数据集中的数据项
list_data(dataset_id="your-dataset-id-here")

# 删除特定数据（软删除 - 更安全，保留共享实体）
delete(data_id="data-uuid", dataset_id="dataset-uuid", mode="soft")

# 删除特定数据（硬删除 - 移除孤立实体）
delete(data_id="data-uuid", dataset_id="dataset-uuid", mode="hard")

开发与调试

调试

使用调试器运行：

mcp dev src/server.py

打开带超时的检查器：

http://localhost:5173?timeout=120000

开发cognee时应用新变更需执行：

如有需要，在cognee文件夹中更新依赖
uv sync --dev --all-extras --reinstall
mcp dev src/server.py

开发

使用本地cognee需：

取消注释cognee-mcp pyproject.toml文件中的以下行并设置cognee根路径：
```
#"cognee[postgres,codegraph,gemini,huggingface,docs,neo4j] @ file:/Users/<username>/Desktop/cognee"
```
注意将file:/Users/<username>/Desktop/cognee替换为实际cognee根路径。
在mcp文件夹中用uv安装依赖：
```
uv sync --reinstall
```

行为准则

我们致力于为社区提供愉快且尊重的开源体验。详见CODE_OF_CONDUCT。

💫 贡献者

✨ 功能特性

🚀 快速开始

🐳 Docker使用指南

重要提示：Docker与直接使用区别

Docker API模式

简易用法（自动处理localhost）：

显式使用host.docker.internal（Mac/Windows）：

Linux系统（使用主机网络或容器IP）：

🔗 MCP客户端配置

SSE传输配置（推荐）

Claude CLI（最简单方式）

手动配置

HTTP传输配置（备选方案）

Claude CLI（最简单方式）

手动配置

双重配置示例

🌐 API模式

直连模式（默认）

API模式

💻 基础使用

可用工具

开发与调试

调试

开发

行为准则

💫 贡献者

星标历史

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐