🧠 KnowGraph: Graph RAG & MCP Server for Code (v1.1.1 🚀)

Transform your AI coding assistant with deep code understanding

"Your code is not just text, it's a living graph."
Shift from vector similarity to the deterministic clarity of Graph Theory and Joern Code Property Graph.

v1.1.1 — CLI reachability fix (python -m knowgraph) on top of v1.1.0's hybrid retrieval, grounding & anti-hallucination. Evidence-backed answers with entity-level verification, temporal filtering, SC-quoted (P3-verified) relation extraction, and API version negotiation.

⚡ Quick Start • 📚 Full Documentation • 📘 Example Usage Guide

---

🔬 Why KnowGraph?

KnowGraph is an MCP (Model Context Protocol) server that enhances AI coding assistants with:

• 🎯 Graph-Based Code Understanding: Follows real relationships (imports, calls, inheritance)
• 🔍 Deep Security Analysis: Joern-powered vulnerability detection (SQL injection, buffer overflows via policy scans; XSS/XXE/SSRF via taint analysis)
• ⚓ Answer Grounding: Verifies generated answers against graph evidence (anti-hallucination)
• 📊 Impact Analysis: Predict ripple effects of code changes
• 🕰️ Time-Travel Debugging: Version control for your knowledge graph
• 💬 Conversational Memory: Index and search your AI chat history
• ⚡ High Performance: ~30s indexing, <1s re-indexing (small project) with smart caching

Supported Languages: Python, JavaScript/TypeScript, Java, C/C++, Go, Rust, C#, Scala, PHP, Ruby, Kotlin, Swift, and more (14+ languages)

---

⚡ Quick Start

1. Installation

pip install knowgraph

# Install optional components (recommended): Joern code analysis + the
# all-MiniLM-L6-v2 embedding model for dense retrieval. Both go under ~/.knowgraph.
knowgraph-setup

Tip: If your shell reports knowgraph: command not found (its Scripts folder isn't on PATH, common on Windows), run python -m knowgraph instead — it behaves identically and needs no PATH setup.

2. MCP Server Configuration

Global Timeout (all MCP servers at once)

If you want a single timeout setting for all MCP servers, set it globally:

{
  "mcpServers": {
    "__global__": {
      "timeout": 300000
    }
  }
}

This sets a 300-second (5 minute) default timeout for every MCP tool call — ideal for slow/free providers where synthesis may take 60–120s.

For Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "knowgraph": {
      "command": "knowgraph",
      "args": ["serve"],
      "timeout": 120000,
      "env": {
        "KNOWGRAPH_API_KEY": "sk-your-openai-key-here",
        "KNOWGRAPH_API_BASE_URL": "https://openrouter.ai/api/v1",
        "KNOWGRAPH_LLM_MODEL": "x-ai/grok-4.1-fast",
        "KNOWGRAPH_LLM_REQUEST_TIMEOUT": "120",
        "KNOWGRAPH_LLM_SYNTHESIS_TIMEOUT": "115",
        "KNOWGRAPH_QUERY_TOTAL_TIMEOUT": "118"
      }
    }
  }
}

Timeout tip: For slow/free providers, raise all three env vars to 90–120s and the MCP client timeout to 120000 (120s) so the client doesn't cut before the server responds. KNOWGRAPH_LLM_REQUEST_TIMEOUT is the per-call budget; KNOWGRAPH_LLM_SYNTHESIS_TIMEOUT is the whole-synthesis budget (retries included); KNOWGRAPH_QUERY_TOTAL_TIMEOUT is the entire query-path budget (retrieval + synthesis). Raise your MCP client's tool-call timeout to match (≥ 120s).

For Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "knowgraph": {
      "command": "knowgraph",
      "args": ["serve"],
      "timeout": 120000,
      "env": {
        "KNOWGRAPH_API_KEY": "sk-your-openai-key-here",
        "KNOWGRAPH_API_BASE_URL": "https://openrouter.ai/api/v1",
        "KNOWGRAPH_LLM_MODEL": "x-ai/grok-4.1-fast",
        "KNOWGRAPH_LLM_REQUEST_TIMEOUT": "120",
        "KNOWGRAPH_LLM_SYNTHESIS_TIMEOUT": "115",
        "KNOWGRAPH_QUERY_TOTAL_TIMEOUT": "118"
      }
    }
  }
}

For Antigravity

Add to ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "knowgraph": {
      "command": "knowgraph",
      "args": ["serve"],
      "timeout": 120000,
      "env": {
        "KNOWGRAPH_API_BASE_URL": "https://openrouter.ai/api/v1",
        "KNOWGRAPH_LLM_MODEL": "x-ai/grok-4.1-fast",
        "KNOWGRAPH_API_KEY": "sk-your-openai-key-here",
        "KNOWGRAPH_LLM_REQUEST_TIMEOUT": "120",
        "KNOWGRAPH_LLM_SYNTHESIS_TIMEOUT": "115",
        "KNOWGRAPH_QUERY_TOTAL_TIMEOUT": "118"
      },
      "disabled": false
    }
  }
}

Using OpenRouter (Alternative LLM Provider)

{
  "mcpServers": {
    "knowgraph": {
      "command": "knowgraph",
      "args": ["serve"],
      "env": {
        "KNOWGRAPH_API_BASE_URL": "https://openrouter.ai/api/v1",
        "KNOWGRAPH_LLM_MODEL": "x-ai/grok-4.1-fast",
        "KNOWGRAPH_API_KEY": "sk-or-v1-your-openrouter-key-here"
      },
      "disabled": false
    }
  }
}

3. Restart Your AI Editor

That's it! KnowGraph is now ready to use.

---

📚 Documentation

For detailed usage, configuration, and advanced features, see the User Guide.

Quick Links:

• Installation & Setup
• MCP Server Integration
• Joern Code Analysis
• Graph Engineering: Grounding & Anti-Hallucination
• Advanced Querying
• Performance Optimization
• Security Analysis
• Troubleshooting
• 📘 Example Usage Guide: All commands, combinations and workflows.
• Architecture

---

🤝 Contributing

Contributions are welcome! Please see our Contributing Guide for details.

---

📄 License

MIT

---

🔗 Links

• GitHub: yunusgungor/knowgraph
• Documentation: User Guide
• Issues: Report a bug
• MCP Protocol: Model Context Protocol
• Joern: Code Property Graph