MCP Server Configuration

Environment Variables

# FalkorDB Configuration
FALKORDB_HOST=localhost
FALKORDB_PORT=6379
FALKORDB_USERNAME=          # Optional
FALKORDB_PASSWORD=          # Optional
FALKORDB_DEFAULT_READONLY=false  # Set to 'true' for read-only mode

# Transport Mode
MCP_TRANSPORT=stdio         # 'stdio' (default) or 'http'
MCP_PORT=3000              # Port for HTTP transport
MCP_API_KEY=               # Optional API key for HTTP transport

# Logging (optional)
ENABLE_FILE_LOGGING=false

Transport Modes

stdio (default)

Used for direct integration with AI clients like Claude Desktop. Communication happens via standard input/output.

MCP_TRANSPORT=stdio

HTTP

Exposes the MCP server over HTTP for remote or networked access:

MCP_TRANSPORT=http
MCP_PORT=3000
MCP_API_KEY=your-secret-api-key  # Optional but recommended

When using HTTP transport, clients connect via the MCP Streamable HTTP protocol. API key authentication is enforced via the Authorization: Bearer <key> header when MCP_API_KEY is set.

Read-Only Mode for Replica Instances

Enable read-only mode by default to prevent writes to replica instances:

FALKORDB_DEFAULT_READONLY=true

Use cases:

• Replica instances: Prevent writes to read replicas in replication setups
• Production safety: Ensure critical data isn’t accidentally modified
• Reporting/analytics: Run queries for dashboards without risk of data changes
• Multi-tenant environments: Provide read-only access to certain users

Running Multiple Instances

You can configure multiple MCP servers for different FalkorDB instances:

{
  "mcpServers": {
    "falkordb-dev": {
      "command": "npx",
      "args": ["-y", "@falkordb/mcpserver@latest"],
      "env": {
        "FALKORDB_HOST": "dev.falkordb.local",
        "FALKORDB_DEFAULT_READONLY": "false"
      }
    },
    "falkordb-prod-replica": {
      "command": "npx",
      "args": ["-y", "@falkordb/mcpserver@latest"],
      "env": {
        "FALKORDB_HOST": "replica.falkordb.com",
        "FALKORDB_DEFAULT_READONLY": "true"
      }
    }
  }
}

<style>
.faq-accordion {
  margin: 1.5rem 0;
  border: 1px solid var(--border-color, #3d434b);
  border-radius: 6px;
  overflow: hidden;
}

/* Group-level: <summary> title bar (when <details> wrapper is used) */
summary.faq-accordion-title {
  list-style: none;
  margin: 0;
  padding: 0.6rem 1rem;
  background: var(--code-background-color, #2d333b);
  font-weight: 700;
  font-size: 1rem;
  border-bottom: 1px solid var(--border-color, #3d434b);
  color: var(--body-text-color, #e0e0e0);
  display: flex;
  align-items: center;
  gap: 0.5rem;
  cursor: pointer;
  user-select: none;
}

summary.faq-accordion-title::-webkit-details-marker {
  display: none;
}

/* Group-level collapse indicator (rotates when open) */
summary.faq-accordion-title::before {
  content: "▶";
  font-size: 0.65rem;
  transition: transform 0.2s ease;
  flex-shrink: 0;
}

.faq-accordion[open] > summary.faq-accordion-title::before {
  transform: rotate(90deg);
}

summary.faq-accordion-title:hover {
  filter: brightness(1.1);
}

.faq-count {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  min-width: 1.4em;
  height: 1.4em;
  padding: 0 0.3em;
  border-radius: 9999px;
  background: var(--link-color, #a78bfa);
  color: #1b1f23;
  font-size: 0.7rem;
  font-weight: 700;
  line-height: 1;
  flex-shrink: 0;
}

.faq-item {
  border-bottom: 1px solid var(--border-color, #3d434b);
}

.faq-item:last-child {
  border-bottom: none;
}

.faq-item summary.faq-question {
  list-style: none;
  padding: 0.75rem 1rem;
  cursor: pointer;
  font-weight: 600;
  color: var(--link-color, #a78bfa);
  background: var(--body-background-color, #1b1f23);
  display: flex;
  align-items: center;
  gap: 0.5rem;
  user-select: none;
}

.faq-item summary.faq-question::-webkit-details-marker {
  display: none;
}

/* Question-level collapse indicator (rotates when open) */
.faq-item summary.faq-question::before {
  content: "▶";
  font-size: 0.65rem;
  transition: transform 0.2s ease;
  flex-shrink: 0;
}

.faq-item[open] > summary.faq-question::before {
  transform: rotate(90deg);
}

.faq-item summary.faq-question:hover {
  background: var(--code-background-color, #2d333b);
  color: var(--link-color, #a78bfa);
  filter: brightness(1.15);
}

.faq-item > .faq-answer {
  padding: 0.75rem 1rem 0.75rem 2rem;
  background: var(--sidebar-color, #161a1f);
  color: var(--body-text-color, #e0e0e0);
  line-height: 1.65;
}

.faq-item > .faq-answer > *:first-child {
  margin-top: 0;
}

.faq-item > .faq-answer > *:last-child {
  margin-bottom: 0;
}
</style><details class="faq-accordion">
  <summary class="faq-accordion-title">
    Frequently Asked Questions
    <span class="faq-count">5</span>
  </summary><details class="faq-item">
    <summary class="faq-question">What environment variables are required?</summary>
    <div class="faq-answer"><p>Only <code class="language-plaintext highlighter-rouge">FALKORDB_HOST</code> and <code class="language-plaintext highlighter-rouge">FALKORDB_PORT</code> are required (defaulting to <code class="language-plaintext highlighter-rouge">localhost</code> and <code class="language-plaintext highlighter-rouge">6379</code>). Username, password, transport mode, and logging are all optional configuration options.</p>
</div>
  </details><details class="faq-item">
    <summary class="faq-question">What is the difference between stdio and HTTP transport?</summary>
    <div class="faq-answer"><p><strong>stdio</strong> is the default mode for direct integration with AI clients like Claude Desktop, communicating via standard input/output. <strong>HTTP</strong> exposes the server over a network port for remote access, supporting API key authentication via Bearer tokens.</p>
</div>
  </details><details class="faq-item">
    <summary class="faq-question">How do I secure the HTTP transport mode?</summary>
    <div class="faq-answer"><p>Set <code class="language-plaintext highlighter-rouge">MCP_API_KEY</code> to a secret value. When configured, clients must include an <code class="language-plaintext highlighter-rouge">Authorization: Bearer &lt;key&gt;</code> header in their requests. This is optional but recommended for any network-exposed deployment.</p>
</div>
  </details><details class="faq-item">
    <summary class="faq-question">Can I connect to multiple FalkorDB instances?</summary>
    <div class="faq-answer"><p>Yes. Configure multiple MCP server entries in your client config, each with different <code class="language-plaintext highlighter-rouge">FALKORDB_HOST</code> values and settings. For example, have a <code class="language-plaintext highlighter-rouge">falkordb-dev</code> instance with writes enabled and a <code class="language-plaintext highlighter-rouge">falkordb-prod-replica</code> in read-only mode.</p>
</div>
  </details><details class="faq-item">
    <summary class="faq-question">When should I use read-only mode?</summary>
    <div class="faq-answer"><p>Enable <code class="language-plaintext highlighter-rouge">FALKORDB_DEFAULT_READONLY=true</code> for replica instances, production environments where accidental writes must be prevented, reporting/analytics dashboards, and multi-tenant setups where certain users should only have read access.</p>
</div>
  </details></details>