Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

MCP Server

nimlangserver can run as an MCP (Model Context Protocol) server, exposing Nim-aware tools to AI assistants and coding agents such as GitHub Copilot, Claude Code, and Gemini. This lets AI tools inspect Nim code semantically instead of relying on plain-text search.

Contents

Setup

VSCode

MCP support is bundled with the vscode-nim extension. Installing the extension gives you a working LSP server, a working MCP server, and the accompanying skill — no additional configuration needed.

Other agents

  1. Install nimlangserver.

  2. Copy the matching MCP config file from this repository to your project:

    AgentConfig file
    Claude Code.mcp.json
    GitHub Copilot CLI.mcp.json
    Gemini CLI.gemini/settings.json
    OpenCodeopencode.json

  3. Copy the SKILL.md file to your project:

    AgentDestination
    Claude Code.claude/skills/nim-mcp-tools/
    GitHub Copilot CLI.github/skills/nim-mcp-tools/
    Gemini CLI.gemini/skills/nim-mcp-tools/
    OpenCode.opencode/skills/nim-mcp-tools/

  4. Open the Nim project root in your AI tool.

Available tools

ToolDescription
nimFindReferencesFind all references to a symbol at a given position.
nimFindSymbolsSearch workspace symbols by name query.
nimFindTypeDefinitionGo to the type definition of a symbol.
nimListSymbolsList all symbols defined in a file.
nimCheckProjectRun diagnostics for the whole project.
nimCheckFileRun diagnostics for a single file.

Usage

Before using the MCP tools, load the skill with the /nim-mcp-tools slash command in your AI tool.

With the skill loaded, your AI tool will automatically prefer Nim-specific MCP tools over general-purpose tools like grep when working with Nim code.

Example: if you ask your AI to find and remove all references to a symbol foo, it will:

  1. Call nimFindSymbols("foo") to locate all definitions.
  2. Call nimFindReferences on each definition.
  3. Perform the deletion.

You can also invoke tools directly: "Call nimCheckFile on @myfile.nim."

Demo

Why use nimlangserver as an MCP server?

Nim's identifier resolution is not purely textual — the same symbol can be spelled differently (printThing, printthing, print_thing) and can be called indirectly through templates or macros. Plain text search misses these cases.

Consider:

proc printThing(thing: string) =
  echo thing

template doActionWithThing(action: untyped, thing: string): untyped =
  `action Thing`(thing)

when isMainModule:
  printThing("Hello")
  printthing("World")
  print_thing("Nim is awesome")
  doActionWithThing(print, "No really, Nim is so cool")

printThing is used 4 times: directly, twice with alternative spelling, and once through a template. Without MCP, an AI relying on text search misses 3 of those 4 usages. With MCP and nimFindSymbols + nimFindReferences, all 4 are found reliably.

With MCP, the result is guaranteed to be correct because it uses the same semantic analysis that the compiler uses.