cognee‑mcp-将cognee的内存引擎作为模型上下文协议服务器运行
Demo . Learn more · Join Discord · Join r/AIMemory
在终端或IDE中为代理和来自任何使用MCP的客户端的查询构建内存。
✨ 特性
- 多种传输方式——选择流式HTTP——传输HTTP（建议用于web部署）、SSE——传输SSE（实时流式传输）或stdio（经典管道，默认）
- 云模式 –连接到 Cognee Cloud 通过
--serve-url或COGNEE_SERVICE_URLenv var（请参见 连接模式) - API模式 –连接到已运行的Cognee FastAPI服务器（请参阅 连接模式)
- 最小内存API –仅暴露
remember,recall，以及forget用于代理内存工作流 - 集成日志记录——所有操作都写入一个旋转文件（参见get_log_file_location（）），并镜像到开发中的控制台
- 会话感知内存——通过一个内存存储快速会话缓存条目或永久图形内存
remember工具 - 专注回忆——通过一次查询记忆
recall具有可选会话和搜索控件的工具 - 简单删除-通过一个操作删除数据集或所有拥有的内存
forget工具
请参阅我们的文档 这里 了解更多信息。
🚀 快速入门
- 克隆同源仓库
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密钥，以便使用默认cognie配置进行快速设置
LLM_API_KEY="YOUR_OPENAI_API_KEY"- 使用stdio运行cognee mcp服务器（默认）
python src/server.py或通过SSE传输响应
python src/server.py --transport sse或使用Streamable HTTP传输运行（建议用于web部署）
python src/server.py --transport http --host 127.0.0.1 --port 8000 --path /mcp您可以使用我们的 模板。 要使用不同的LLM提供程序/数据库配置，请查看我们的 文档.
🐳 Docker使用
如果你宁愿在容器中运行cognee-mcp，你有两个选择：
- 本地建设
1. 确保您位于/cogniee根目录中，并且有一个新的 .env 仅包含您的 LLM_API_KEY （以及您选择的设置）。
1. 删除所有旧映像并重新生成：
docker rmi cognee/cognee-mcp:main || true
docker build --no-cache -f cognee-mcp/Dockerfile -t cognee/cognee-mcp:main .1. 运行它：
# For HTTP transport (recommended for web deployments)
docker run -e TRANSPORT_MODE=http --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main
# For SSE transport
docker run -e TRANSPORT_MODE=sse --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main
# For stdio transport (default)
docker run -e TRANSPORT_MODE=stdio --env-file ./.env --rm -it cognee/cognee-mcp:main在运行时安装可选依赖项：
您可以在运行容器时安装可选依赖项，方法是设置 EXTRAS 环境变量：
# Install a single optional dependency group at runtime
docker run \
-e TRANSPORT_MODE=http \
-e EXTRAS=aws \
--env-file ./.env \
-p 8000:8000 \
--rm -it cognee/cognee-mcp:main
# Install multiple optional dependency groups at runtime (comma-separated)
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 -Web抓取功能 - distributed -模态分布式执行 - langchain -LangChain集成 - llama-index -LlamaIdex集成 - anthropic -人类模型 - groq -Groq模型 - mistral -西北风模型 - ollama / huggingface -本地模型支持 - docs -文件处理 - codegraph -代码分析 - monitoring -哨兵和廊坊监控 - redis -Redis支持 - 更多（参见 pyproject.toml 完整列表）
- 从Docker Hub拉取 （无需构建）：
# With HTTP transport (recommended for web deployments)
docker run -e TRANSPORT_MODE=http --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main
# With SSE transport
docker run -e TRANSPORT_MODE=sse --env-file ./.env -p 8000:8000 --rm -it cognee/cognee-mcp:main
# With stdio transport (default)
docker run -e TRANSPORT_MODE=stdio --env-file ./.env --rm -it cognee/cognee-mcp:main在运行时安装可选依赖项：
# Install optional dependencies from Docker Hub image
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容器连接到主机上运行的Cognie API服务器，请执行以下操作：
简单用法（自动处理本地主机）：
# Start your Cognee API server on the host
python -m cognee.api.client
# Run MCP container in API mode - localhost is automatically converted!
docker run \
-e TRANSPORT_MODE=sse \
-e API_URL=http://localhost:8000 \
-e API_TOKEN=your_auth_token \
-p 8001:8000 \
--rm -it cognee/cognee-mcp:main注： 容器将自动转换 localhost 到 host.docker.internal 在Mac/Windows/Docker桌面上。您将在日志中看到一条显示转换的消息。
显式host.docker.internal（Mac/Windows）：
# Or explicitly use host.docker.internal
docker run \
-e TRANSPORT_MODE=sse \
-e API_URL=http://host.docker.internal:8000 \
-e API_TOKEN=your_auth_token \
-p 8001:8000 \
--rm -it cognee/cognee-mcp:main在Linux上（使用主机网络或容器IP）：
# Option 1: Use host network (simplest)
docker run \
--network host \
-e TRANSPORT_MODE=sse \
-e API_URL=http://localhost:8000 \
-e API_TOKEN=your_auth_token \
--rm -it cognee/cognee-mcp:main
# Option 2: Use host IP address
# First, get your host IP: ip addr show docker0
docker run \
-e TRANSPORT_MODE=sse \
-e API_URL=http://172.17.0.1:8000 \
-e API_TOKEN=your_auth_token \
-p 8001:8000 \
--rm -it cognee/cognee-mcp:mainAPI模式的环境变量：
API_URL：正在运行的Cognie API服务器的URLAPI_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您应该看到您的服务器已连接：
Checking MCP server health...
cognee-sse: http://localhost:8000/sse (SSE) - ✓ Connected手动配置
克劳德(~/.claude.json)
{
"mcpServers": {
"cognee": {
"type": "sse",
"url": "http://localhost:8000/sse"
}
}
}光标(~/.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您应该看到您的服务器已连接：
Checking MCP server health...
cognee-http: http://localhost:8000/mcp (HTTP) - ✓ Connected手动配置
克劳德(~/.claude.json)
{
"mcpServers": {
"cognee": {
"type": "http",
"url": "http://localhost:8000/mcp"
}
}
}光标(~/.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"
}
}
}注： 仅启用您实际运行的服务器以避免连接错误。
🌐 连接模式
MCP服务器支持三种连接模式：
直接模式 （默认）
MCP服务器直接导入并使用带有本地数据库（SQLite、LanceDB、Ladybug）的cognee库。这是具有完整功能支持的默认模式。
云模式
连接到 Cognee Cloud 或远程Cognee实例。服务器调用 cognee.serve() 在启动时，所有SDK操作都透明地路由到云端。不需要本地数据库。
通过CLI标志：
python src/server.py --serve-url https://your-instance.cognee.ai --serve-api-key ck_...通过环境变量（零配置）：
export COGNEE_SERVICE_URL="https://your-instance.cognee.ai"
export COGNEE_API_KEY="ck_..."
python src/server.pyDocker云模式：
docker run \
-e TRANSPORT_MODE=sse \
-e COGNEE_SERVICE_URL=https://your-instance.cognee.ai \
-e COGNEE_API_KEY=ck_... \
-p 8000:8000 \
--rm -it cognee/cognee-mcp:main云模式参数/环境变量：
--serve-url/COGNEE_SERVICE_URL：Cognee Cloud或远程实例URL--serve-api-key/COGNEE_API_KEY：实例的API密钥
在云模式下，数据库迁移会自动跳过。
API模式
MCP服务器通过HTTP请求连接到已运行的Cognee FastAPI服务器。这在以下情况下很有用：
- 您有一个集中的Cognie API服务器正在运行
- 您想将MCP服务器与知识图后端分离
- 您需要多个MCP服务器来共享相同的知识图
在API模式下启动MCP服务器：
# Start your Cognee FastAPI server first (default port 8000)
cd /path/to/cognee
python -m cognee.api.client
# Then start the MCP server in API mode
cd cognee-mcp
python src/server.py --api-url http://localhost:8000 --api-token YOUR_AUTH_TOKEN不同传输方式的API模式：
# With SSE transport
python src/server.py --transport sse --api-url http://localhost:8000 --api-token YOUR_TOKEN
# With HTTP transport
python src/server.py --transport http --api-url http://localhost:8000 --api-token YOUR_TOKEN带有Docker的API模式：
# On Mac/Windows (use host.docker.internal to access host)
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
# On Linux (use host network)
docker run \
--network host \
-e TRANSPORT_MODE=sse \
-e API_URL=http://localhost:8000 \
-e API_TOKEN=YOUR_TOKEN \
--rm -it cognee/cognee-mcp:mainAPI模式的命令行参数：
--api-url：正在运行的Cognee FastAPI服务器的基本URL（例如。，http://localhost:8000)--api-token：API的身份验证令牌（可选，如果API已启用身份验证，则必需）
API模式的Docker环境变量：
API_URL：正在运行的Cognee FastAPI服务器的基本URLAPI_TOKEN：身份验证令牌（可选，如果API已启用身份验证，则为必需）
API模式行为： MCP服务器有意只公开内存API： remember, recall，以及 forget. 在API模式下，这些工具直接调用Cognie API服务器端点。操作助手，如 cognify, search, list_data, delete, prune, improve，文档检索助手包括 保持在内部，不作为MCP工具暴露。
💻 基本用法
MCP服务器通过工具公开其功能。从任何MCP客户端（Cursor、Claude Desktop、Cline、Roo等）调用它们。
可用工具
MCP服务器公开了三个工具：
- 记住：将数据存储在内存中。随着
session_id：快速会话缓存。没有session_id：永久图形存储器 - 召回：使用自动路由搜索内存。在以下情况下首先搜索会话缓存
session_id提供，然后进入永久图 - 忘记：按数据集名称删除内存，或使用删除所有拥有的内存
everything=True
示例：
# Store permanent memory
remember(data="Cognee MCP now exposes a focused memory API.", dataset_name="main_dataset")
# Store session memory
remember(data="Temporary working note", session_id="agent-session-1")
# Recall from memory
recall(query="What changed in the MCP server?", session_id="agent-session-1")
# Delete one dataset
forget(dataset="main_dataset")开发与调试
调试
要使用调试器，请运行： bash mcp dev src/server.py
已超时的打开检查器： http://localhost:5173?timeout=120000
要在开发cognee时应用新更改，您需要执行以下操作：
- 如果需要，更新cognee文件夹中的依赖关系
uv sync --dev --all-extras --reinstallmcp dev src/server.py
发展
为了使用本地同源词：
- 取消对同源mcp中以下行的注释
pyproject.toml文件并设置cognee根路径。
#"cognee[postgres,codegraph,gemini,huggingface,docs,neo4j] @ file:/Users//Desktop/cognee"记得更换 file:/Users//Desktop/cognee 使用您的实际认知根路径。
- 在mcp文件夹中安装带有uv的依赖项
uv sync --reinstall行为准则
我们致力于让开源成为我们社区的一种愉快和尊重的体验。看 行为准则 了解更多信息。