Faulkner DB

Faulkner DB MCP Server lets you run a Python-based MCP server that exposes a temporal knowledge graph for capturing, querying, and analyzing architectural decisions and implementation patterns over time. It is designed to work with FalkorDB to provide fast, structured insights that help you reduce technical debt and onboard teammates quickly.

How to use

You interact with Faulkner DB through an MCP client to perform core knowledge graph operations. Start the MCP server locally and connect your client (for example Claude Desktop/Code) to the Faulkner DB MCP endpoint. Use the server to record decisions, query decisions by topic or timeframe, store successful patterns, document failures, and explore related knowledge. You can view a network graph, a timeline of understanding, and a dashboard to monitor health and activity.

The MCP server is configured to run as a local process and connects to FalkorDB and PostgreSQL to enable temporal graph storage, embeddings, and reranking for fast search. You can also inspect a FalkorDB UI for graph data and a health endpoint to verify the MCP server is operational.

How to install

Prerequisites: install Docker and Docker Compose on your system. Ensure you have Python 3.8+ available to run the MCP server code. You may also need Git to clone repositories.

1. Start with a manual setup flow (recommended if you want full control): clone the repository, start the FalkorDB and PostgreSQL stack, and then configure the MCP server for Claude.

git clone https://github.com/platano78/faulkner-db.git
cd faulkner-db/docker

# Copy environment template
cp .env.example .env

# Edit .env and set POSTGRES_PASSWORD

# Start services
docker-compose up -d

2. Configure Claude to connect to Faulkner DB as an MCP server. Add the following block to your Claude configuration file to register the MCP server.

{
  "mcpServers": {
    "faulkner_db": {
      "command": "python3",
      "args": ["-m", "mcp_server.server"],
      "env": {
        "PYTHONPATH": "/path/to/faulkner-db",
        "FALKORDB_HOST": "localhost",
        "FALKORDB_PORT": "6379"
      }
    }
  }
}

3. Access services to verify the setup. Use the FalkorDB UI and the MCP endpoints exposed by the server to confirm connectivity.

Configuration and security

Environment variables shown for the MCP server enable proper runtime behavior. The following variables must be provided when configuring the MCP server in Claude or other MCP clients.

PYTHONPATH=/path/to/faulkner-db
FALKORDB_HOST=localhost
FALKORDB_PORT=6379

The MCP server uses FalkorDB for the graph data store and PostgreSQL for metadata. Ensure network access between the MCP server, FalkorDB, and PostgreSQL, and secure your endpoints as appropriate for your environment.

Troubleshooting

Docker containers not starting

docker-compose ps

docker-compose logs -f

docker-compose restart

FalkorDB connection errors

docker-compose ps
lsof -i :6379

docker-compose logs falkordb

MCP server not detected in Claude

Verify configuration path matches your OS
Restart Claude Desktop/Code after config changes
Check Python path in MCP config is correct
Ensure Docker stack is running

Notes and tips

The Faulkner DB MCP server integrates seven MCP tools to manage decisions, timelines, and gaps. You can record decisions, query decisions by topic or timeframe, add successful patterns, document failures, and explore related knowledge.

You can view a Network Graph, Timeline, and Dashboard at the dedicated UI endpoints to understand how your project knowledge evolves over time.

Available tools

add_decision

Record architectural decisions with full context and rationale.

query_decisions

Perform hybrid search for decisions by topic and timeframe.

add_pattern

Store successful implementation patterns.

add_failure

Document failed attempts and lessons learned.

find_related

Traverse the graph to discover related knowledge nodes.

detect_gaps

Run NetworkX-based structural analysis to identify knowledge gaps.

get_timeline

Show how understanding evolved over time for a topic.