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.
G
GEML MCP Server
Community
An MCP server for GEML documents, enabling block-at-a-time edits with validation.
GitHub source repository ↗
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.
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.
Tools
geml_get
Read one block (e.g., by #id).
geml_set
Replace a block, optionally using content from another template or file.
geml_add
Insert a fragment after another block, preserving its ids.
geml_delete
Remove a specified block.
geml_rename
Rename a block id.
geml_history
View the revision history of a specific block.
geml_revert
Roll back a single block to a previous revision while keeping the rest of the file unchanged.
geml_check
Validate the document, producing diagnostics and a non-zero exit code on errors.
geml_codemap_called_by
Find which methods call a given method.
geml_codemap_calls
Find what methods a given method calls.
geml_codemap_view
View a node or path within the code graph.
geml_codemap_find
Search for methods or paths in the code graph.
Setup
- Install Node.js 22+ on the target machine. 2. For Claude Code, run: claude mcp add geml -- npx -y @geml/geml@latest mcp --root /absolute/path/to/your/docs. 3. For Claude Desktop, add a config entry to claude_desktop_config.json as shown in the provided example. 4. 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"
]
}
}
}
Fit and risk
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.
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).
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 DesktopFull support
Claude CodeFull support
Generic MCP clientFull support