Graphiti

You run a private MCP server that exposes a personality psychology knowledge graph. It supports semantic search and works with MCP clients like Claude Desktop and Cursor, enabling you to query traits, types, frameworks, assessments, and researchers via an API-backed graph database.

How to use

Connect your MCP client to the hosted server using the provided URL and start querying the knowledge graph. You can search for entities by natural language, retrieve related facts, and explore relationships such as trait frameworks and assessment mappings. Use the client to fetch entity summaries, relationships, and recent graph updates to build your applications or research workflows.

How to install

Prerequisites: you need Python and a MCP runner or environment that can start the server. You will also configure Neo4j Aura access and an OpenAI API key for embeddings.

# 1) Clone the server repository
git clone https://github.com/YOUR_USERNAME/graphiti-mcp-server.git
cd graphiti-mcp-server

# 2) Install and sync dependencies if using the development flow
uv sync

# 3) Copy and configure environment variables
cp .env.example .env
# Edit .env to include NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD, OPENAI_API_KEY

4. Start the server in production mode using the Aura configuration, or use the development flow for local testing.

uv run main.py --config config/config-aura.yaml

Additional configuration and startup notes

Configure environment variables to enable secure connections and embedding generation. The server expects these at runtime to connect to the database and to utilize language models for semantic processing.

Notes on deployment and hosting

This MCP server is designed to run privately and can be hosted in your cloud environment. It includes production-ready configuration for Neo4j Aura and a structured YAML setup for production or local development. When deploying publicly, ensure access is restricted to authorized MCP clients and that secret keys are kept in secure environment variables.

Security and environment variables

Set and protect the following environment variables to enable database access and language model features: NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD, OPENAI_API_KEY. Store these values securely and do not commit them to version control.

Troubleshooting tips

If the server fails to start, verify that your Neo4j Aura credentials are correct, the OpenAI API key is valid, and that the Aura instance is reachable from your network. Check the startup logs for connection errors to the database or API endpoints and verify that the correct YAML config is being loaded.

Helpful hints

For faster development cycles, keep a local development YAML config alongside your test data. When ready for production, switch to the Aura-configured YAML and ensure your environment variables are set in your hosting environment.

Supported MCP endpoints and capabilities

The server provides endpoints to search for entity summaries by semantic similarity, retrieve facts and relationships between entities, access details of specific relationships, and manage episodes or additions to the knowledge graph. You can also check the server and database status and monitor recent activity.

Configuration details

Configuration is handled via YAML files in the config/ directory. The production file targets Neo4j Aura, while a local development file supports running with a local or Docker-based Neo4j instance. Ensure the following environment variables are available at runtime: NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD, OPENAI_API_KEY.

Examples and usage guidance

Use the MCP client to perform semantic searches and fact queries against the personality psychology knowledge graph. Typical use cases include querying for trait frameworks, mapping assessments to theory, and exploring relationships between researchers and frameworks.

Available tools

search_nodes

Search for entity summaries by semantic similarity to a query.

search_facts

Retrieve relationships or facts between entities based on semantic context.

get_entity_edge

Fetch details of a specific relationship between two entities.

get_episodes

Retrieve recent episodes or entries for a given group in the graph.

add_episode

Add new information or relationships to the knowledge graph.

get_status

Check the current server and database status.