Cognee MCP Server: GraphRAG Memory Ingestion & Search

Overview

Cognee MCP Server implements a Model Context Protocol (MCP) compatible service that ingests, processes, and searches memory using a GraphRAG (graph + retrieval-augmented generation) approach. It is designed to convert documents, conversations, or structured records into a memory graph whose nodes are enriched with vector embeddings and metadata, enabling fast similarity search combined with graph-aware traversal and reasoning. The result is more accurate, context-aware retrieval that can support downstream LLM prompt construction and multi-step reasoning.

This server is useful when you need a production-ready ingestion pipeline and retrieval layer that is customizable: you can define how content is chunked, embedded, indexed, and linked into a graph. It fits use cases such as personal assistants that maintain long-term memory, enterprise knowledge bases that require contextual chains, or RAG applications that need both nearest-neighbor and relationship-aware results.

Features

• Pluggable GraphRAG pipelines: configurable stages for chunking, enrichment, embedding, indexing, and graph linking.
• MCP-compatible API: interact via standard HTTP endpoints for ingestion, search, and graph queries.
• Vector search + graph traversal: combine similarity search with relationship-aware expansions for higher-quality context.
• Multiple storage backends: support for file-based, SQL, and external vector stores (FAISS, Milvus, Pinecone, Weaviate — via connectors).
• Extensible embeddings and LLMs: easily swap embedding providers (OpenAI, Hugging Face, local models) and downstream LLMs.
• Batch and streaming ingestion: handle single documents, datasets, or streaming sources with checkpointing and retries.
• Observability: basic logging, metrics endpoints, and configurable log levels.
• Docker and Kubernetes friendly: deployable via Docker Compose or standard k8s manifests.

Installation / Configuration

Clone the repository and run locally with Docker, or build and run from source.

Clone the repo:

git clone https://github.com/topoteretes/cognee.git
cd cognee/cognee-mcp

Run using Docker:

# build image (if needed)
docker build -t cognee-mcp:latest .

# run with env config
docker run -p 8080:8080 \
  -e MCP_PORT=8080 \
  -e EMBEDDING_PROVIDER=openai \
  -e OPENAI_API_KEY=${OPENAI_API_KEY} \
  cognee-mcp:latest

Docker Compose example (docker-compose.yml):

version: "3.8"
services:
  mcp:
    image: cognee-mcp:latest
    ports:
      - "8080:8080"
    environment:
      MCP_PORT: "8080"
      EMBEDDING_PROVIDER: "openai"
      OPENAI_API_KEY: "${OPENAI_API_KEY}"
      STORAGE_BACKEND: "faiss"
      VECTOR_DB_URL: "file:/data/faiss.index"
    volumes:
      - ./data:/data

Configuration file (pipeline.yml) — example pipeline stages:

pipeline:
  - name: chunk
    type: text_chunker
    params:
      chunk_size: 1000
      overlap: 200
  - name: metadata
    type: enrich_metadata
    params: {}
  - name: embed
    type: embedder
    params:
      provider: openai
      model: text-embedding-3-large
  - name: index
    type: vector_index
    params:
      backend: faiss
      index_path: /data/faiss.index
  - name: graph_link
    type: graph_connector
    params:
      min_similarity: 0.75
      max_hops: 2

Environment variables (common)

Available Tools / Resources

• REST API endpoints: /ingest, /search, /graph, /status
• CLI helper: cognee-mcp (for quick ingestion and pipeline validation)
• Example pipeline configs: several pre-built YAMLs for docs, conversations, and structured logs
• Connectors: adapters for FAISS, Pinecone, Milvus, Weaviate, PostgreSQL/S3 storage
• SDK snippet (Python): small client to call /ingest and /search (included in repo examples)
• Demo datasets: example documents and conversation logs to try locally

Use Cases

• Personal assistant long-term memory

  • Ingest user interactions and documents; on query, retrieve contextually appropriate memories using vector search and graph traversal to find chains of related events or facts.

• Customer support knowledge base

  • Ingest product docs, ticket histories, and support transcripts. Use GraphRAG to surface related tickets and technical documentation together, helping agents or automated assistants craft accurate responses.

• Research or content discovery

  • Index papers, notes, and references. Graph edges can represent citations or topical similarity, enabling multi-hop retrieval (find related papers, then their key experiments).

• Codebase / engineering memory

  • Ingest code comments, PR descriptions, and design docs. Combine semantic search (similar code snippets or issues) with graph links (module dependencies, ownership) to discover root causes or impacted components.

Example: Ingest and Search

Ingest a document (curl):

curl -X POST "http://localhost:8080/ingest" \
  -H "Content-Type: application/json" \
  -d '{"id":"doc-123","text":"Your long document text here","metadata":{"source":"wiki","project":"alpha"}}'

Search:

curl -X POST "http://localhost:8080/search" \
  -H "Content-Type: application/json" \
  -d '{"query":"How do I configure X for project alpha?", "top_k":5, "graph_expand_hops":1}'

Response will include nearest-node results and optionally expanded graph context useful for prompt assembly.

Next Steps

• Review example pipeline YAMLs and pick one to customize for your data.
• Configure an appropriate vector backend for your scale (FAISS for local, Pinecone/Milvus for managed).
• Add or swap embedding providers depending on latency, cost, and accuracy requirements.
• Integrate with your application to build context-aware prompts or to drive multi-step reasoning workflows.

For full source and examples, see the project repository: https://github.com/topoteretes/cognee/tree/main/cognee-mcp