Skip to content
Back to search

graphiti-mcp-server

Graphiti MCP Server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gifflet--graphiti-mcp-server/badge.svg)](/listings/gifflet--graphiti-mcp-server)

HTML

<a href="/listings/gifflet--graphiti-mcp-server"><img src="/api/listings/gifflet--graphiti-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Docker and Docker Compose - Python 3.10 or higher - OpenAI API key - Minimum 4GB RAM (recommended 8GB) - 2GB free disk space

Quick Start πŸš€

1. Clone the repository:

git clone https://github.com/gifflet/graphiti-mcp-server.git
cd graphiti-mcp-server

2. Set up environment variables:

cp .env.sample .env

3. Edit `.env` with your configuration:

# Required for LLM operations
OPENAI_API_KEY=your_openai_api_key_here
MODEL_NAME=gpt-4.1-mini

# Optional: Custom OpenAI endpoint (e.g., for proxies)
# OPENAI_BASE_URL=https://api.openai.com/v1

# Neo4j Configuration (defaults work with Docker)
NEO4J_URI=bolt://neo4j:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=demodemo

4. Start the services:

docker compose up -d

5. **Verify installation:**

# Check if services are running
docker compose ps

# Check logs
docker compose logs graphiti-mcp

Alternative: Environment Variables

You can run with environment variables directly:

OPENAI_API_KEY=your_key MODEL_NAME=gpt-4.1-mini docker compose up

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 321 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Graphiti MCP Server 🧠
  2. [![Python Version](https://img.shields.io/badge/python-3.10-blue.svg)](https://www.python.org/downloads/release/python-3100/)
  3. [![License](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
  4. [![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](https://www.docker.com/)
  5. > 🌟 A powerful knowledge graph server for AI agents, built with Neo4j and integrated with Model Context Protocol (MCP).
  6. ## πŸš€ Features
  7. - πŸ”„ Dynamic knowledge graph management with Neo4j
  8. - πŸ€– Seamless integration with OpenAI models
  9. - πŸ”Œ MCP (Model Context Protocol) support
  10. - 🐳 Docker-ready deployment
  11. - 🎯 Custom entity extraction capabilities
  12. - πŸ” Advanced semantic search functionality
  13. ## πŸ› οΈ Installation
  14. ### Prerequisites
  15. - Docker and Docker Compose
  16. - Python 3.10 or higher
  17. - OpenAI API key
  18. - Minimum 4GB RAM (recommended 8GB)
  19. - 2GB free disk space
  20. ### Quick Start πŸš€
  21. 1. Clone the repository:
  22. ```bash
  23. git clone https://github.com/gifflet/graphiti-mcp-server.git
  24. cd graphiti-mcp-server
  25. ```
  26. 2. Set up environment variables:
  27. ```bash
  28. cp .env.sample .env
  29. ```
  30. 3. Edit `.env` with your configuration:
  31. ```bash
  32. # Required for LLM operations
  33. OPENAI_API_KEY=your_openai_api_key_here
  34. MODEL_NAME=gpt-4.1-mini
  35. # Optional: Custom OpenAI endpoint (e.g., for proxies)
  36. # OPENAI_BASE_URL=https://api.openai.com/v1
  37. # Neo4j Configuration (defaults work with Docker)
  38. NEO4J_URI=bolt://neo4j:7687
  39. NEO4J_USER=neo4j
  40. NEO4J_PASSWORD=demodemo
  41. ```
  42. 4. Start the services:
  43. ```bash
  44. docker compose up -d
  45. ```
  46. 5. **Verify installation:**
  47. ```bash
  48. # Check if services are running
  49. docker compose ps
  50. # Check logs
  51. docker compose logs graphiti-mcp
  52. ```
  53. ### Alternative: Environment Variables
  54. You can run with environment variables directly:
  55. ```bash
  56. OPENAI_API_KEY=your_key MODEL_NAME=gpt-4.1-mini docker compose up
  57. ```
  58. ## πŸ”§ Configuration
  59. ### Service Ports 🌐
  60. | Service | Port | Purpose |
  61. |---------|------|---------|
  62. | Neo4j Browser | 7474 | Web interface for graph visualization |
  63. | Neo4j Bolt | 7687 | Database connection |
  64. | Graphiti MCP | 8000 | MCP server endpoint |
  65. ### Environment Variables πŸ”§
  66. #### OpenAI Configuration
  67. | Variable | Required | Default | Description |
  68. |----------|----------|---------|-------------|
  69. | `OPENAI_API_KEY` | βœ… | - | Your OpenAI API key |
  70. | `OPENAI_BASE_URL` | ❌ | - | Custom OpenAI API endpoint (consumed by OpenAI SDK) |
  71. | `MODEL_NAME` | ❌ | `gpt-4.1-mini` | Main LLM model to use |
  72. | `SMALL_MODEL_NAME` | ❌ | `gpt-4.1-nano` | Small LLM model for lighter tasks |
  73. | `LLM_TEMPERATURE` | ❌ | `0.0` | LLM temperature (0.0-2.0) |
  74. | `EMBEDDER_MODEL_NAME` | ❌ | `text-embedding-3-small` | Embedding model |
  75. #### Neo4j Configuration
  76. | Variable | Required | Default | Description |
  77. |----------|----------|---------|-------------|
  78. | `NEO4J_URI` | ❌ | `bolt://neo4j:7687` | Neo4j connection URI |
  79. | `NEO4J_USER` | ❌ | `neo4j` | Neo4j username |
  80. | `NEO4J_PASSWORD` | ❌ | `demodemo` | Neo4j password |
  81. #### Server Configuration
  82. | Variable | Required | Default | Description |
  83. |----------|----------|---------|-------------|
  84. | `MCP_SERVER_HOST` | ❌ | - | MCP server host binding |
  85. | `SEMAPHORE_LIMIT` | ❌ | `10` | Concurrent operation limit for LLM calls |
  86. #### Azure OpenAI Configuration (Optional)
  87. For Azure OpenAI deployments, use these environment variables instead of the standard OpenAI configuration:
  88. | Variable | Required | Default | Description |
  89. |----------|----------|---------|-------------|
  90. | `AZURE_OPENAI_ENDPOINT` | βœ…* | - | Azure OpenAI endpoint URL |
  91. | `AZURE_OPENAI_API_VERSION` | βœ…* | - | Azure OpenAI API version |
  92. | `AZURE_OPENAI_DEPLOYMENT_NAME` | βœ…* | - | Azure OpenAI deployment name |
  93. | `AZURE_OPENAI_USE_MANAGED_IDENTITY` | ❌ | `false` | Use Azure managed identity for auth |
  94. | `AZURE_OPENAI_EMBEDDING_ENDPOINT` | ❌ | - | Separate endpoint for embeddings |
  95. | `AZURE_OPENAI_EMBEDDING_API_VERSION` | ❌ | - | API version for embeddings |
  96. | `AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME` | ❌ | - | Deployment name for embeddings |
  97. | `AZURE_OPENAI_EMBEDDING_API_KEY` | ❌ | - | Separate API key for embeddings |
  98. \* Required when using Azure OpenAI
  99. **Notes:**
  100. - `OPENAI_BASE_URL` is consumed directly by the OpenAI Python SDK, useful for proxy configurations or custom endpoints
  101. - `SEMAPHORE_LIMIT` controls concurrent LLM API calls - decrease if you encounter rate limits, increase for higher throughput
  102. - Azure configuration is an alternative to standard OpenAI - don't mix both configurations
  103. ### Neo4j Settings πŸ—„οΈ
  104. Default configuration for Neo4j:
  105. - Username: `neo4j`
  106. - Password: `demodemo`
  107. - URI: `bolt://neo4j:7687` (within Docker network)
  108. - Memory settings optimized for development
  109. ### Docker Environment Variables 🐳
  110. You can run with environment variables directly:
  111. ```bash
  112. OPENAI_API_KEY=your_key MODEL_NAME=gpt-4.1-mini docker compose up
  113. ```
  114. For Azure OpenAI:
  115. ```bash
  116. AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com \
  117. AZURE_OPENAI_API_VERSION=2024-02-01 \
  118. AZURE_OPENAI_DEPLOYMENT_NAME=your-deployment \
  119. OPENAI_API_KEY=your_key \
  120. docker compose up
  121. ```
  122. ## πŸ”Œ Integration
  123. ### Cursor IDE Integration πŸ–₯️
  124. 1. **Configure Cursor MCP settings:**
  125. ```json
  126. {
  127. "mcpServers": {
  128. "Graphiti": {
  129. "command": "uv",
  130. "args": ["run", "graphiti_mcp_server.py"],
  131. "env": {
  132. "OPENAI_API_KEY": "your_key_here"
  133. }
  134. }
  135. }
  136. }
  137. ```
  138. 2. **For Docker-based setup:**
  139. ```json
  140. {
  141. "mcpServers": {
  142. "Graphiti": {
  143. "url": "http://localhost:8000/sse"
  144. }
  145. }
  146. }
  147. ```
  148. 3. **Add Graphiti rules to Cursor's User Rules** (see `graphiti_cursor_rules.mdc`)
  149. 4. **Start an agent session in Cursor**
  150. ### Other MCP Clients
  151. The server supports standard MCP transports:
  152. - **SSE (Server-Sent Events):** `http://localhost:8000/sse`
  153. - **WebSocket:** `ws://localhost:8000/ws`
  154. - **Stdio:** Direct process communication
  155. ## πŸ’» Development
  156. ### Local Development Setup
  157. 1. **Install dependencies:**
  158. ```bash
  159. # Using uv (recommended)
  160. curl -LsSf https://astral.sh/uv/install.sh | sh
  161. uv sync
  162. # Or using pip
  163. pip install -r requirements.txt
  164. ```
  165. 2. **Start Neo4j locally:**
  166. ```bash
  167. docker run -d \
  168. --name neo4j-dev \
  169. -p 7474:7474 -p 7687:7687 \
  170. -e NEO4J_AUTH=neo4j/demodemo \
  171. neo4j:5.26.0
  172. ```
  173. 3. **Run the server:**
  174. ```bash
  175. # Set environment variables
  176. export OPENAI_API_KEY=your_key
  177. export NEO4J_URI=bolt://localhost:7687
  178. # Run with stdio transport
  179. uv run graphiti_mcp_server.py
  180. # Or with SSE transport
  181. uv run graphiti_mcp_server.py --transport sse --use-custom-entities
  182. ```
  183. ### Testing
  184. ```bash
  185. # Run basic connectivity test
  186. curl http://localhost:8000/health
  187. # Test MCP endpoint
  188. curl http://localhost:8000/sse
  189. ```
  190. ## πŸ” Troubleshooting
  191. ### Common Issues
  192. #### 🐳 Docker Issues
  193. ```bash
  194. # Clean up and restart
  195. docker compose down -v
  196. docker compose up --build
  197. # Check disk space
  198. docker system df
  199. ```
  200. ### Logs and Debugging
  201. ```bash
  202. # View all logs
  203. docker compose logs -f
  204. # View specific service logs
  205. docker compose logs -f graphiti-mcp
  206. docker compose logs -f neo4j
  207. # Enable debug logging
  208. docker compose up -e LOG_LEVEL=DEBUG
  209. ```
  210. ### Performance Issues
  211. - **Memory:** Increase Neo4j heap size in `docker-compose.yml`
  212. - **Storage:** Monitor Neo4j data volume usage
  213. - **Network:** Check for firewall blocking ports 7474, 7687, 8000
  214. ## πŸ—οΈ Architecture
  215. ```
  216. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  217. β”‚ MCP Client β”‚ β”‚ Graphiti MCP β”‚ β”‚ Neo4j β”‚
  218. β”‚ (Cursor) │◄──►│ Server │◄──►│ Database β”‚
  219. β”‚ β”‚ β”‚ (Port 8000) β”‚ β”‚ (Port 7687) β”‚
  220. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  221. β”‚
  222. β–Ό
  223. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  224. β”‚ OpenAI API β”‚
  225. β”‚ (LLM Client) β”‚
  226. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  227. ```
  228. ### Components
  229. - **Neo4j Database:** Graph storage and querying
  230. - **Graphiti MCP Server:** API layer and LLM operations
  231. - **OpenAI Integration:** Entity extraction and semantic processing
  232. - **MCP Protocol:** Standardized AI agent communication
  233. ## 🀝 Contributing
  234. Contributions are welcome! Please feel free to submit a Pull Request.
  235. ## πŸ“ License
  236. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  237. ## πŸ™ Acknowledgments
  238. - [Neo4j](https://neo4j.com/) team for the amazing graph database
  239. - [OpenAI](https://openai.com/) for their powerful LLM models
  240. - [MCP community](https://modelcontextprotocol.io/) for the protocol specification
  241. - [Graphiti Core](https://github.com/griptape-ai/graphiti) for the knowledge graph framework
  242. ---
  243. **Need help?** Open an issue or check our [troubleshooting guide](#-troubleshooting) above.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.