Provides graph search and traversal capabilities via Graphiti on Neo4j, enabling discovery of entities and relationships in the knowledge graph.
Provides text embedding generation for query and document vectors, enabling semantic search for both graph and vector RAG tools.
Provides vector similarity search and BM25 full-text ranking via pgvector, enabling document retrieval based on semantic and exact-term matching.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@python-mcp-server What connects Tesla and battery technology?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server that gives AI agents access to a Graphiti knowledge graph and a pgvector document store for grounded, evidence-backed responses.
🔍 Hybrid graph search — semantic + BM25 + graph traversal via Graphiti
📚 Vector RAG — pgvector similarity search; query strings are embedded internally via OpenAI (no pre-computed vectors required from callers)
🧾 Evidence retrieval, not fake verification — verify_fact returns
related graph evidence; the calling LLM judges entailment
⚡ Fail fast — client errors surface as MCP errors, not silent empty results
⚙️ Clean config split — cfg.yml for config, env vars for secrets only
Related MCP server: Memory MCP
Tool | Input | Returns |
|
| Graph entities/relationships |
|
| Document chunks ranked by similarity |
|
|
|
|
| Graph results + document chunks |
All tools take strings — embeddings are generated server-side.
Resources: knowledge://instructions, knowledge://examples.
Prompt: answer_with_verification.
pip install python-mcp-server
# or
uvx python-mcp-servercfg.yml holds all non-secret config. Secrets live only in environment
variables — never in cfg.yml, never in the Postgres URL.
cfg.ymllocal:
log_level: DEBUG
neo4j:
uri: bolt://localhost:7687
user: neo4j
database: neo4j
postgres:
host: localhost
port: 5432
database: knowledge
user: postgres
embeddings_table: energy_embeddings
embedding_model: text-embedding-3-smallThe server selects the top-level key based on the ENV env var (default local).
A beta section is also supported.
export NEO4J_PASSWORD="..."
export POSTGRES_PASSWORD="..."
export OPENAI_API_KEY="..."
export ENV="local"from python_mcp_server import create_server
from python_mcp_server.config import Config, Neo4jConfig, PostgresConfig, LogLevel
config = Config(
log_level=LogLevel.INFO,
neo4j=Neo4jConfig(uri="bolt://localhost:7687", user="neo4j", database="neo4j"),
postgres=PostgresConfig(
host="localhost", port=5432, database="knowledge", user="postgres",
embeddings_table="energy_embeddings",
embedding_model="text-embedding-3-small",
),
)
server = create_server(
config=config,
neo4j_password="...",
postgres_password="...",
openai_api_key="...",
)export NEO4J_PASSWORD=... POSTGRES_PASSWORD=... OPENAI_API_KEY=...
claude mcp add domain-expert -- uvx python-mcp-serverclaude_desktop_config.json){
"mcpServers": {
"knowledge-graph": {
"command": "uvx",
"args": ["python-mcp-server"],
"env": {
"NEO4J_PASSWORD": "...",
"POSTGRES_PASSWORD": "...",
"OPENAI_API_KEY": "..."
}
}
}
}from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio
mcp = MCPServerStdio("uvx", "python-mcp-server")
agent = Agent(toolsets=[mcp])
result = await agent.run("What connects Tesla and battery technology?")pgvector table expected by rag_search:
CREATE TABLE energy_embeddings (
id SERIAL PRIMARY KEY,
title TEXT,
content TEXT NOT NULL,
book TEXT,
section_level TEXT,
analysis_relevance TEXT,
embedding vector(1536), -- text-embedding-3-small
content_tsv tsvector
GENERATED ALWAYS AS (to_tsvector('english', content)) STORED
);
CREATE INDEX ON energy_embeddings USING ivfflat (embedding vector_cosine_ops);
CREATE INDEX idx_content_tsv ON energy_embeddings USING gin(content_tsv);Embedding dimension must match embedding_model in cfg.yml.
rag_search issues two rankings against this table — cosine over embedding
and BM25 over content_tsv — and fuses them via Reciprocal Rank Fusion
(k=60). Exact-term matches (protocol field names, enum values, requirement
IDs) come through the BM25 leg that pure cosine would miss.
git clone <repo> && cd python-mcp-server
uv sync --dev
cp template-secrets.env .env # fill in secrets
uv run poe checks # deptry, black, ruff, mypy, bandit, pip-audit
uv run poe cover # tests with coverage
uv run python-mcp-serversrc/python_mcp_server/
├── clients/
│ ├── embedder.py # OpenAI embeddings (injected)
│ ├── graphiti_client.py # Neo4j via Graphiti
│ └── rag_client.py # pgvector similarity search
├── config.py # cfg.yml loader
├── models.py # Pydantic response models
├── server.py # FastMCP tools, resources, prompt
└── __main__.py # CLI entry pointString-in, evidence-out. Callers pass natural language; the server handles embeddings and returns typed Pydantic results.
No fake verification. verify_fact returns evidence; the caller LLM
decides entailment. The server never invents a verified: bool.
Fail fast. Database errors propagate to the MCP client so Claude sees "Neo4j unreachable" instead of "no results."
Config vs. secrets are separate concerns. cfg.yml is checked in;
passwords and API keys never are.
Search both the knowledge graph and document vectors.
USE WHEN: You need both structured facts and supporting context.
Inputs: query (required), limit. Returns: Combined results from both graph and vector search.
Search documents using vector similarity for context.
USE WHEN: You need detailed context, explanations, or source documents. The query string is embedded internally; no pre-computed vector needed.
Inputs: query (required), limit. Returns: result
Search factual knowledge in the Graphiti knowledge graph.
USE WHEN: You need verified facts, entities, relationships, or structured knowledge. Combines semantic search, BM25, and graph traversal.
Inputs: query (required), limit. Returns: Collection of search results from knowledge graph.
Retrieve knowledge-graph evidence relevant to a statement.
USE WHEN: You want to check a claim against the graph. Returns related facts; the caller judges whether they support or contradict the statement. No boolean verdict — entailment is the caller's job.
Inputs: statement (required), limit. Returns: Graph evidence relevant to a statement. Caller judges entailment.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 4 tools
Each tool has a reasonably clear purpose: graph knowledge search, document vector search, combined search, and claim verification. The only mild overlap is between search_knowledge and verify_fact, but the descriptions distinguish general exploration from targeted claim checking.
Names are all lowercase snake_case and readable, but the pattern is inconsistent: search_knowledge and verify_fact are verb_noun, while rag_search and combined_search are qualifier_search. This makes the naming convention less predictable across the set.
Four tools is a well-scoped size for a retrieval-focused server. Each tool has a distinct role, and combined_search earns a place as a convenience for workflows needing both knowledge graph and document context.
For a read-only search and verification server, the core operations are covered: graph search, RAG search, combined search, and claim verification. Missing ingestion or update/delete tools would be a gap only if the server were meant to manage the underlying knowledge store, which the descriptions do not indicate.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Cloud or self-hosted knowledge for AI agents: hybrid search, reranking, GraphRAG, scoped MCP tools.
Persistent memory and knowledge graphs for AI agents. Hybrid search, context checkpoints, and more.
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
