CODESYS MCP Server

A Model Context Protocol server for CODESYS Development System V3. It gives MCP clients curated CODESYS guidance, Structured Text writing help, searchable local PDF documentation, and optional live lookup of allowlisted official CODESYS pages.

The server can run over HTTP at /mcp or over stdio for direct CLI and agent integration. Official pages are summarized and cited rather than copied into the project. Primary official sources include CODESYS Online Help and CODESYS Examples.

Tools

• search_codesys_docs: search curated and/or official CODESYS guidance.
• get_codesys_topic: explain a known topic such as POUs, function blocks, timers, tasks, variables, libraries, debugging, or Structured Text.
• codesys_writing_guidance: provide practical CODESYS and Structured Text design guidance for a requested task.
• list_codesys_pdfs: list PDF documents available in the configured PDF folder.
• search_codesys_pdfs: search text extracted from local PDF documents.
• get_codesys_pdf: return extracted text from a specific local PDF document.
• get_codesys_page: fetch the full text content of any allowlisted CODESYS documentation URL.
• crawl_codesys_help: crawl and index the CODESYS help site for searchable documentation.

What It Does

• Searches curated CODESYS guidance for concepts, syntax, and workflow help.
• Explains common CODESYS topics such as POUs, function blocks, timers, tasks, variables, libraries, debugging, and Structured Text.
• Provides practical Structured Text and project-structure guidance.
• Searches local PDF manuals and notes placed in docs/pdfs/.
• Fetches and summarizes allowlisted official CODESYS documentation pages.
• Crawls the official help site to build a searchable index.

Install For A Human

Use this when you want to run the server yourself on your machine.

Prerequisites:

• Node.js 20 or newer
• npm

From a fresh clone:

npm install
cp .env.example .env
npm run build

Start the HTTP server:

npm start

Or start the stdio server:

npm run start:stdio

By default, the HTTP server listens on http://0.0.0.0:3000/mcp.

Install For An LLM Or Agent

AI agent? Read agent.md — it contains the complete, step-by-step self-installation guide written specifically for you. Start there.

Use this section when an LLM is being instructed to connect itself to the server as an MCP client.

Suggested instruction to give the LLM:

Read agent.md in the repository root. It contains the exact steps to install this MCP server into yourself.

1. Build the project first:

npm install
npm run build

2. Prefer stdio transport for local agent integration.
3. Add the server to the client using the local build output:

claude mcp add --transport stdio codesys-docs -- node ./dist/src/cli.js --stdio

4. If the client needs HTTP instead, start the server and register the endpoint:

npm start

claude mcp add --transport http codesys-docs http://localhost:3000/mcp

5. If the agent can only work from a published package, use:

claude mcp add --transport stdio codesys-docs -- npx -y codesys-mcp-server --stdio

For Codex CLI:

codex mcp add codesys-docs -- node ./dist/src/cli.js --stdio

Quick Start

npm install
cp .env.example .env
npm run build
npm start

The server listens on http://0.0.0.0:3000/mcp by default.

Docker

docker compose up --build

The compose file mounts ./docs/pdfs into the container as read-only, so you can add PDFs locally without rebuilding the image.

PDF Folder

Put CODESYS manuals, vendor PDFs, project notes, datasheets, or exported documentation in:

docs/pdfs/

The MCP server extracts text from .pdf files in that folder and makes them available through:

• search_codesys_docs with sourceMode: "pdf" or sourceMode: "all"
• list_codesys_pdfs
• search_codesys_pdfs
• get_codesys_pdf

PDF text extraction is best for searchable text PDFs. Scanned image-only PDFs may return little or no content unless OCR has already been applied. Extracted text may omit diagrams, screenshots, formatting, and some tables, so important engineering details should be verified against the original PDF.

Configuration

Variable	Default	Description
PORT	3000	HTTP port.
HOST	0.0.0.0	Bind host.
OFFICIAL_LOOKUP_ENABLED	true	Enables live official CODESYS page lookup.
OFFICIAL_LOOKUP_TIMEOUT_MS	3500	Fetch timeout per official page.
OFFICIAL_LOOKUP_CACHE_TTL_SECONDS	3600	In-memory cache TTL for official pages.
PDF_SEARCH_ENABLED	true	Enables text extraction/search for local PDFs.
PDF_DOCS_DIR	docs/pdfs	Folder scanned for .pdf files.
PDF_MAX_TEXT_CHARS	200000	Maximum extracted text stored per PDF.

CLI Usage

# HTTP server (default)
node dist/src/cli.js
npm start

# Stdio server (for Claude Code / Codex CLI MCP integration)
node dist/src/cli.js --stdio
npm run start:stdio

Acceptance Checks

npm test
npm run build
curl http://localhost:3000/healthz