MarkdownLM MCP Server

MarkdownLM is the persistent memory and governance layer between your team and your AI coding agents. Define your rules once. Enforced everywhere. Every session.

Note:

The MarkdownLM knowledge base supports the following categories for all rules, patterns, and decisions:

• architecture: Layering, boundaries, system design
• stack: Frameworks, libraries, versions
• testing: Test frameworks, coverage, patterns
• deployment: CI/CD, platforms, scripts
• security: Auth, validation, secrets
• style: Naming, formatting, organization
• dependencies: Approved/banned packages
• error_handling: Exceptions, logging, monitoring
• business_logic: Domain rules, workflow constraints, business invariants, pricing logic, subscription rules, permission models
• general: Anything else

When using this MCP server, always specify a category. category is a required field on query_knowledge_base.

How it works

1. Your team documents architecture rules, stack decisions, and patterns in MarkdownLM.
2. This MCP server gives AI coding agents three focused tools to query and validate against that knowledge.
3. Agents validate code against your rules before suggesting changes — violations never reach PRs.

Setup

1. Get your API key

1. Log in to MarkdownLM
2. Go to Settings → API & MCP
3. Generate an API key

2. Configure your AI tool

Pick your tool below. All use the same npm package — one codebase, every platform.

Claude Code (CLI)

claude mcp add markdownlm -e MARKDOWNLM_API_KEY=mdlm_your_key_here -e MARKDOWNLM_API_URL=https://markdownlm.com -- npx -y markdownlm-mcp

Or manually edit ~/.claude/claude_code_config.json:

{
  "mcpServers": {
    "markdownlm": {
      "command": "npx",
      "args": ["-y", "markdownlm-mcp"],
      "env": {
        "MARKDOWNLM_API_KEY": "mdlm_your_key_here",
        "MARKDOWNLM_API_URL": "https://markdownlm.com"
      }
    }
  }
}

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "markdownlm": {
      "command": "npx",
      "args": ["-y", "markdownlm-mcp"],
      "env": {
        "MARKDOWNLM_API_KEY": "mdlm_your_key_here",
        "MARKDOWNLM_API_URL": "https://markdownlm.com"
      }
    }
  }
}

Cursor

.cursor/mcp.json in your project root (project-scoped) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "markdownlm": {
      "command": "npx",
      "args": ["-y", "markdownlm-mcp"],
      "env": {
        "MARKDOWNLM_API_KEY": "mdlm_your_key_here",
        "MARKDOWNLM_API_URL": "https://markdownlm.com"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "markdownlm": {
      "command": "npx",
      "args": ["-y", "markdownlm-mcp"],
      "env": {
        "MARKDOWNLM_API_KEY": "mdlm_your_key_here",
        "MARKDOWNLM_API_URL": "https://markdownlm.com"
      }
    }
  }
}

Cline (VS Code)

In the Cline extension settings (MCP Servers):

{
  "mcpServers": {
    "markdownlm": {
      "command": "npx",
      "args": ["-y", "markdownlm-mcp"],
      "env": {
        "MARKDOWNLM_API_KEY": "mdlm_your_key_here",
        "MARKDOWNLM_API_URL": "https://markdownlm.com"
      }
    }
  }
}

VS Code (Native/Extension)

.vscode/mcp.json in your project root:

{
  "servers": {
    "markdownlm": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "markdownlm-mcp"],
      "env": {
        "MARKDOWNLM_API_KEY": "mdlm_your_key_here",
        "MARKDOWNLM_API_URL": "https://markdownlm.com"
      }
    }
  }
}

Tools

query_knowledge_base

Query your team's documented rules before writing code. Returns relevant rules with sources and automatically logs gaps for undocumented decisions.

Inputs

| Field | Required | Description | |---|---|---| | query | ✓ | Natural language question (e.g. "How should I handle auth?") | | category | ✓ | Category of the query: architecture, stack, testing, deployment, security, style, dependencies, error_handling, business_logic, general |

Response — answer, sources[], gap_detected, optional gap_resolution

validate_code

Validate a code snippet against all documented rules. Returns pass/fail with violation details and fix suggestions.

Inputs

| Field | Required | Description | |---|---|---| | code | ✓ | Code snippet to check | | task | ✓ | What the code is supposed to do | | category | ✓ | The knowledge base category relevant to this code |

Response — status (pass/fail), violations[] (rule, message, fix_suggestion), fix_suggestion

resolve_gap

Log a knowledge gap for an undocumented decision. Returns how to handle it based on your preferences: markdownlm (AI resolves), ask_user (wait for human), agent_decide (proceed independently).

Inputs

| Field | Required | Description | |---|---|---| | question | ✓ | The undocumented decision or question | | category | ✓ | Category hint |

Response — gap_detected, resolution_mode, optional resolution, gap_id

Environment variables

| Variable | Required | Default | Description | |---|---|---|---| | MARKDOWNLM_API_KEY | ✓ | — | API key from Settings → API & MCP | | MARKDOWNLM_API_URL | — | https://markdownlm.com | Override for self-hosted or staging |

Rate limiting

100 tool calls per 60 seconds per user.

Logging

All tool calls are logged to stderr as newline-delimited JSON (timestamp, tool name, inputs, outcome). This is safe for stdio MCP transport and can be piped to any log aggregator.

Contributing & Security

This repository is strictly the bridge (the client), not the brain. To protect our intellectual property, infrastructure details, and customer data, please carefully review our Contributing Guidelines and Security Policy before making any modifications.

License

Copyright (c) 2026 MarkdownLM. All Rights Reserved.