GEML MCP Server

Community

An MCP server for GEML documents, enabling block-at-a-time edits with validation.

How to install ↓ Compare GitHub source repository ↗

Category: Dev Tools #20 of 438
Stars: ★ 30 Popular
Transport: stdio (local process)
Runtime: Node.js 22+
Credentials: No credential needed
License: MIT
Last commit: 8 days ago
Tools: 12

68FMRS · C

The GEML MCP server offers a safe way to edit blocks atomically within documents, emphasizing validation and fine-grained revision control. It serves users who have adopted the GEML format. Overall, its capabilities are clearly communicated, and it responds to security concerns through --root boundaries and pre-write validation.

Strongest · Documentation 16/20 Weakest · Reliability 12/20

Reliability

12/20

Security and permissions

14/20

Maintenance

13/20

Documentation

16/20

Setup experience

13/20

Why each score

Reliability 12/20: README claims 600+ tests, ≥95% CI-gated coverage, parse-before-write validation, and .gemlhistory revert, with CI badges — but these are self-reported. No independently verifiable execution evidence of the server's key paths (init handshake, tool list, geml_set rejecting bad writes) is present in the supplied files, so the static cap of 12 applies. Failure handling is well described but unverified.
Security and permissions 14/20: No red-line risks: local stdio transport, mandatory --root confinement with explicit refusal of ../, absolute paths and symlinks, parse-before-write, reversible side effects. Deductions: incomplete disclosure of supply-chain behavior (codemap build downloads a scip indexer), .gemlhistory write behavior details, and the permission model is not verifiable from code in the supplied material.
Maintenance 13/20: Active: v1.10.1, npm package, CI workflows, open governance (GOVERNANCE/CONTRIBUTING), dual licensing (MIT + CC-BY-4.0). But repo license metadata is NOASSERTION (dual-license ambiguity), issue tracker shows 0 open issues and low stars limiting evidence of community maintenance, and no explicit security-response channel is disclosed.
Documentation 16/20: Layered docs: README, mcp-guide.md, bilingual normative specs, playground, and disclosed limitations (lossy projection, unregistered media type). Tool naming mirrors CLI verbs. Deducted because per-tool parameters, error semantics and cost details live behind links not present in the reviewed material.
Setup experience 13/20: Clear install path: npm package, one-command `claude mcp add` and Claude Desktop JSON config, explicit Node 22+ requirement, --root absolute-path guidance. Deducted for absent troubleshooting guidance and optional --graph details deferred to an external guide; not verifiable end-to-end statically.

Static review · not runListed 2026-09-08

Read the FMRS scoring method →

Fit and risk

What it can accessReads local filesWrites / deletes local files

Best for

Documentation workflows that have adopted GEML.
Collaborative authoring with AI agents or scripts where safety is required.
Software development workflows that rely on documentation or code skeletons.

Not for

Repositories that don't use GEML.
As a general-purpose file system tool.
Use cases requiring a network-accessible MCP server.

Required permissions

Read and write access to files under the directory specified by --root, and only that directory.
Fetching packages on demand via npm/npx.
Ability to create and write .gemlhistory sidecar files inside the root.

Risks and side effects

Misconfigured --root may cause unexpected changes, but writes outside the directory are explicitly refused.
Invalid document modifications are refused, but network access is needed for package installation.
History files may grow over time; tracking quotas is outside the root.
Vulnerable to misconfiguration of clients or tools; ensure the --root path is correct.

Setup

Before you start

Runtime：Node.js 22+

Install Node.js 22+ on the target machine.
For Claude Code, run: claude mcp add geml -- npx -y @geml/geml@latest mcp --root /absolute/path/to/your/docs.
For Claude Desktop, add a config entry to claude_desktop_config.json as shown in the provided example.
Optionally, if your repository contains a code graph, additional graph tools become available.

claude_desktop_config.json

{
  "mcpServers": {
    "geml": {
      "command": "npx",
      "args": [
        "-y",
        "@geml/geml@latest",
        "mcp",
        "--root",
        "/absolute/path/to/your/docs"
      ]
    }
  }
}

Shown for Claude Desktop. Other clients may use a different file or key (VS Code uses "servers") — the configurator below converts it.

.vscode/mcp.json

{
  "servers": {
    "geml": {
      "command": "npx",
      "args": [
        "-y",
        "@geml/geml@latest",
        "mcp",
        "--root",
        "/absolute/path/to/your/docs"
      ]
    }
  }
}

Goes in your project's .vscode/mcp.json (VS Code uses a "servers" key).

Terminal

claude mcp add geml -- npx -y @geml/geml@latest mcp --root /absolute/path/to/your/docs

Run it in a terminal; replace any <…> placeholders with your own values first.

Generate and validate client config

Check that it works

Check that tools like geml_get and geml_set appear in the client's tool list, then ask the agent to read a single block (e.g. "show the #hello block"); returning its content proves the connection. Note: --root must be an absolute path; paths outside it are refused.

Troubleshooting

Verify Node 22+ is installed (`node --version`).
Ensure --root is an absolute path and exists.
Test basic operations from the command line: geml check yourfile.geml.
Check that the client launches the server with stdio and permissions allow execution.
Check for write permissions on .gemlhistory.
If the graph tools are missing, check that a code graph index exists (.geml-code-graph/index.geml).

Things to try

Once connected, you can ask your AI assistant things like:

Read just the #budget block from doc.geml
Fix the Q3 row in the FY26 table
Insert the fragment from snippet.geml after #intro
Show the history of the #plan block and revert it one revision

Tools 12

geml_get read-only

Read one block (e.g., by #id).

geml_set writes

Replace a block, optionally using content from another template or file.

geml_add writes

Insert a fragment after another block, preserving its ids.

geml_delete destructive

Remove a specified block.

geml_rename writes

Rename a block id.

geml_history read-only

View the revision history of a specific block.

geml_revert destructive

Roll back a single block to a previous revision while keeping the rest of the file unchanged.

geml_check read-only

Validate the document, producing diagnostics and a non-zero exit code on errors.

Show 4 more tools

geml_codemap_called_by read-only

Find which methods call a given method.

geml_codemap_calls read-only

Find what methods a given method calls.

geml_codemap_view read-only

View a node or path within the code graph.

geml_codemap_find read-only

Search for methods or paths in the code graph.

Use cases

Editing individual blocks in large GEML documents with an AI agent while keeping the rest of the document intact.

Validating document references and introducing structured context via block IDs or content hashes.

Finding and reverting erroneous changes on a block-by-block basis.

For repositories with a code graph, answering call-graph queries at a codebase level.

Supported clients

Claude Desktop

Claude Code

Generic MCP client

Listed from the project's documentation, not tested by this site.

Overview

This server runs over stdio and lets AI agents edit GEML files (plain-text documents based on Markdown) block by block instead of rewriting whole files. It parses every write before committing, refuses changes that would break the document, and maintains a block-level revision history (.gemlhistory) for rollback. It requires a working directory specified via --root and will never write outside that directory. It works with any MCP-compatible client such as Claude Desktop or Claude Code. It can additionally serve read-only code-graph tools to answer questions like "who calls this?" when a code graph is available.

Similar servers

Context7 80 · B

Upstash's official server providing up-to-date third-party library docs for AI coding assistants

★ 63.3k · Tools 2 Compare with this →

NPM Sentinel MCP Server 79 · B

AI-powered NPM package analysis MCP server

★ 18 · Tools 19 Compare with this →

MartinLoop MCP Server 79 · B

An independent control layer that gives AI coding agents budgets, brakes, and receipts

★ 413 Compare with this →

GitHub MCP Server 76 · B

GitHub's official MCP server for managing repos, issues, PRs, and workflows via natural language

★ 33.7k · Tools 15 Compare with this →

Compare with other MCP servers

Source revision 9eaab9a171ed Data synced 2026-10-19 Read the FMRS scoring method