Provides AI agents with deep knowledge of X4: Foundations scripts, schemas, expression types, and game texts for automated script development.
Also known as chemodun/X4CodeSense, x4-script-mcp
- Stars
- 0
- Tools
- 7
- Downloads, 30 days
- —
- Latest version
- 0.5.0
- Last commit
- Oct 24, 2026
- License
- Apache-2.0
What is X4CodeSense MCP?
X4CodeSense provides AI agents with deep knowledge of X4: Foundations scripts, schemas, expression types, and game texts for automated script development. It exposes 7 tools, such as check, describe_element, expression_type.
Summary generated from the project's README
About X4CodeSense MCP server
X4CodeSense provides AI agents with specialized knowledge of X4: Foundations scripts, schemas, and game texts to assist in automated script development. It functions as a read-only bridge that allows agents to access the same deep technical data used by the X4CodeSense VS Code extension. Developers can use it locally via the X4CodeSense extension to serve agents at a specific HTTP port or install it via npm for use with Claude Code, Claude Desktop, or Cursor.
The server requires Node.js 22 or later and can be configured to point to an installed game folder, unpacked vanilla files, or specific extension directories. It provides tools like check, describe_element, and expression_type to help agents understand the complex structure of Mission Director and AI scripts. By using these tools, agents can validate their work against game schemas and expression types without manually searching through XML files or script properties.
What you can do with it
- 1Validate script syntax and structureAn agent can run a check on a script file to identify errors and receive suggested quick fixes.
- 2Explore schema elements and attributesA developer can ask an agent to describe a specific XML element to learn its required attributes and allowed child elements.
Written from the project's README. Every use case is checked against a quote from it.
How to install X4CodeSense MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall X4CodeSense MCP in Claude Code
$ claude mcp add x4-script-mcp -- npx -y x4-script-mcpInstall X4CodeSense MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"x4-script-mcp": {
"command": "npx",
"args": [
"-y",
"x4-script-mcp"
]
}
}
}Install X4CodeSense MCP in VS Code
.vscode/mcp.json
{
"servers": {
"x4-script-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"x4-script-mcp"
]
}
}
}Install X4CodeSense MCP in VS Code CLI
$ code --add-mcp '{"name":"x4-script-mcp","type":"stdio","command":"npx","args":["-y","x4-script-mcp"]}'Install X4CodeSense MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"x4-script-mcp": {
"command": "npx",
"args": [
"-y",
"x4-script-mcp"
]
}
}
}Install X4CodeSense MCP in Codex
$ codex mcp add x4-script-mcp -- npx -y x4-script-mcpInstall X4CodeSense MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.x4-script-mcp] command = "npx" args = ["-y", "x4-script-mcp"]
Install X4CodeSense MCP in Gemini CLI
$ gemini mcp add -s user x4-script-mcp npx -- -y x4-script-mcpInstall X4CodeSense MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"x4-script-mcp": {
"command": "npx",
"args": [
"-y",
"x4-script-mcp"
]
}
}
}X4CodeSense MCP tools 7
Detected from the READMEcheckdescribe_elementexpression_typefindhovertextstatus
| check | — | |
| describe_element | — | |
| expression_type | — | |
| find | — | |
| hover | — | |
| text | — | |
| status | — |
Configuration
X4_GAMEThe installed game, the folder of X4.exe; its files are read from the catalogs.
X4_UNPACKEDThe extracted game files, the folder holding libraries, md and aiscripts; used instead of X4_GAME.
| Name | Description | |
|---|---|---|
| X4_GAME | The installed game, the folder of X4.exe; its files are read from the catalogs. | |
| X4_UNPACKED | The extracted game files, the folder holding libraries, md and aiscripts; used instead of X4_GAME. |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubx4-script-mcp
MCP server for X4: Foundations scripts (AI scripts and Mission Director scripts), built on x4-script-core. It gives AI agents that write scripts what the X4CodeSense VS Code extension knows from the game's own files: the checks with their quick fixes, the elements and attributes of the schemas, the types and properties of expressions, the scripts, cues and texts of the game, its DLCs and the extensions. Its tools only read; the agent writes the files.
The X4CodeSense extension brings it along and offers it to VS Code's agents (Copilot's agent mode) on the game files and extensions set in its settings, with nothing to set up; its command X4CodeSense: Start MCP Server serves it at http://127.0.0.1:47400/mcp for other agents, Copilot CLI sessions among them. Other agents also start it from npm:
# Claude Code
claude mcp add x4 -- npx -y x4-script-mcp --game "C:\Games\X4 Foundations" --extensions C:\mods
{
"mcpServers": {
"x4": {
"command": "npx",
"args": ["-y", "x4-script-mcp", "--unpacked", "C:\\X4\\extracted", "--extensions", "C:\\mods"]
}
}
}
The second is the configuration of Claude Desktop, Cursor and others that take one in that form. It needs Node.js 22 or later. It is also in the MCP Registry as io.github.chemodun/x4-script-mcp, which catalogs such as VS Code's MCP server gallery read; with the X4CodeSense extension installed there is no need to add it from there, which would run a second copy.
Agents use the tools they are told about: say in your agent's instructions (CLAUDE.md, .github/copilot-instructions.md, AGENTS.md) to ask describe_element and expression_type before writing an element or an expression, rather than searching the game's .xsd files and scriptproperties.xml, and to run check after every change to a script. Each call is logged on standard error, which clients show as the server's log: the tool, its arguments, the time and the size of the answer.
Options:
--game <folder>- the installed game, the folder ofX4.exe. Its files and those of its DLCs are read from their catalogs where they lie: nothing is extracted. Used when--unpackedis not given. Also beside--unpacked, the mods installed there that the extensions depend on or patch are read from it for the patches, packed ones from their catalogs.--installed-dependencies- with--game, the installed mods the extensions depend on count as a whole: their cues, scripts and texts resolve.--unpacked <folder>- the extracted vanilla game files, the folder holdinglibraries,md,aiscriptsandt.- Without
--gameand--unpacked, theX4_UNPACKEDenvironment variable gives the extracted files, elseX4_GAMEthe installed game; either option given wins over both variables. --extensions <folder>- an extension, or a folder of extensions: those the agent writes and those they refer to. Their scripts and texts are read besides the game's. May be given several times; without it, the current folder.--language <number>- the language texts are shown in,44(English) by default; the game'slibraries/languages.xmllists the numbers.--no-structure- report unknown elements, attributes and values, missing required attributes and text inside elements only, not the order and completeness of child elements.--no-type-guesses- type variables only by what the scripts and the schemas state, not by guesses from the names and documentation of actions (create_shipa ship).--library-patch-unknown-elements <severity>- how severe an element is that a patch of a library file brings in where the file's schema does not declare it:error,warning(default) orinfo. The library schemas lag behind the files: every DLC adds<extension>to a module's<category>, which no schema declares.--port <number>- serve Streamable HTTP athttp://127.0.0.1:<port>/mcpinstead of standard input and output, for agents that are given a URL;0picks a free port. The game files are then read at once, and every client shares them. Only clients on this machine are served: a request naming another host, or from a web page of another site, is refused. A port in use ends it with exit code 1.-h,--help- usage.
The game files are read on the first call, a few seconds. The extensions' files are watched: a script or text file the agent writes, changes or deletes is read again before the next call, and a file a call names is always taken as it is on disk. An extension added, or a content.xml changed, reads them all again.
Tools
Lines and columns count from 1, columns in UTF-16 code units, as editors count them. A place is given as file, line, column, endLine, endColumn, with text, the line it is on, and game: true for a file of the game or a DLC, which may lie in the catalogs only. Answers are JSON; a tool that cannot answer says why, as an error.
check-paths: files and folders;text: what to check instead of the one file inpathsas it is on disk;severity: the least severe finding to report. A folder is checked as x4-script-check checks it: themd,aiscriptsandlibrariesfolders in it and one level deeper. The findings with their quick fixes (edits that do not overlap,preferredfor the one an editor applies on its own), in the shape of the checker's JSON, and their counts.describe_element-name,script(mdoraiscripts) orlibrary(the schema a library file names, by its file name:librariesforjobs.xml,unlocks),parentfor an element declared differently in different places (param,actions),attributefor one attribute in full. The element's documentation, its attributes with their types, whether they are required, their defaults, whether the value is an expression, and the first of their allowed values (all, with their documentation, for one attribute in full); the child elements it allows. For a name the schema does not know, similar ones.expression_type-expression, a keyword and its properties such asplayer.ship.sector, ordatatype, such asship;script;filter. Each step with what it resolved to, its type and description; the datatype of the result with its supertypes, and its properties asname → type, with how many those of the types derived from it add. Withfilter, the properties whose names contain it, those of the derived types too, with their descriptions. A variable has no type here: the step after it is matched against every datatype's properties.find-query,limit. Mission Director scripts, AI scripts, cues, libraries and interrupt library items by name: whole names first, then those that start with the query, then those that contain it; a query with a dot matches qualified names,md.Setup.Start.definition,references-file,line,column. Where what is named there is defined, or every place that names it, in the game, its DLCs and the extensions: cues, scripts, libraries, labels, variables, orders, texts; a definition also in the schemas andscriptproperties.xml.hover-file,line,column. What the editor's hover shows there, as Markdown, with the range it covers: an element or attribute with its documentation, a step of a property chain with its type, a variable with its type and where it is set, a cue or script with where it is defined, a{page, id}text as the game shows it. In patches too, for what they bring in.text-pageandid, orpagealone for its texts, orsearchfor the texts that hold all its words;language,limit. The text as the game shows it, references resolved, and as it is written when that differs, with the file it comes from and the languages it exists in.status- the game folder, the extension folders, how many scripts and texts were read, and the problems met reading them.
Part of X4CodeSense. Apache License 2.0.
X4CodeSense MCP questions
How do I add X4CodeSense MCP to Claude Code?
Run claude mcp add x4-script-mcp -- npx -y x4-script-mcp in your terminal. Add --scope user to make it available in every project.
How do I add X4CodeSense MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does X4CodeSense MCP provide?
It exposes 7 tools, including check, describe_element, expression_type, find, hover.
Can the server write files?
No, the tools are read-only; the AI agent is responsible for writing the actual files.
How do I add this to Claude Code?
You can add it using the command: claude mcp add x4 -- npx -y x4-script-mcp --game "C:\Games\X4 Foundations" --extensions C:\mods
What are the requirements to run the server?
The server requires Node.js version 22 or later.
Does it support DLCs and extensions?
Yes, it reads scripts, texts, and schemas from the game, its DLCs, and any specified extensions.