forthling MCP server
Commit Nov 9, 2026Lets AI agents run Forth-2012 code within a secure sandbox that maintains session state, stacks, and definitions between calls.
Also known as DeSchaker/forthling
- Stars
- 0
- Tools
- 5
- Downloads, 30 days
- —
- Latest version
- 0.2.5
- Last commit
- Nov 9, 2026
- License
- MIT
What is forthling MCP?
forthling lets AI agents run Forth-2012 code within a secure sandbox that maintains session state, stacks, and definitions between calls. It exposes 5 tools, such as forth_eval, forth_stack, forth_words.
Summary generated from the project's README
About forthling MCP server
Forthling provides a secure sandbox for AI agents to execute Forth-2012 code. It is designed for use with MCP clients like Claude Desktop and Claude Code, allowing models to maintain a persistent session where defined words, stacks, and memory stay intact between consecutive calls. The server runs over stdio and can be installed as a pre-built bundle or via cargo.
Developers can interact with the environment using specific tools such as forth_eval for running code, forth_stack to inspect current values, and forth_reset to clear the session. The system includes specialized libraries for JSON processing, SQLite in-memory databases, regular expressions, and scientific computing. It also supports an optional HTTP feature that allows controlled network access to specific hosts via the --allow-host flag.
Safety is managed through strict resource limits, including maximum execution steps, time limits, and memory constraints for definitions and output. All files are kept in memory rather than on disk, ensuring that the execution environment remains isolated and contained within the sandbox.
What you can do with it
- 1Execute persistent Forth sessionsAn agent can define new words and use them in subsequent calls because the session state is maintained.
Written from the project's README. Every use case is checked against a quote from it.
forthling MCP tools 5
Detected from the READMEforth_evalforth_stackforth_wordsforth_helpforth_reset
| forth_eval | — | |
| forth_stack | — | |
| forth_words | — | |
| forth_help | — | |
| forth_reset | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabledeschaker/forthling is public and reachablegithub.com/deschaker/forthling ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/deschaker/forthling ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model5 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubforthling-mcp
An MCP server that lets AI agents (Claude Code, Claude Desktop and other MCP clients) run Forth in forthling, always in its sandbox. The agent keeps one session: the words it defines and the stacks stay between calls.
Installing
Without Rust, as an MCP bundle: download forthling.mcpb from the
latest release and open it in
Claude Desktop (or another client that installs .mcpb files). The bundle holds the
server for Windows (x64), macOS (Apple Silicon and Intel) and Linux (x64).
From crates.io, with Rust 1.85 or newer:
cargo install forthling-mcp
It builds SQLite along, which takes a C compiler (on Windows that of Visual Studio, which
Rust there uses anyway); cargo install forthling-mcp --no-default-features leaves SQLite
out. From a clone of the repository: cargo install --path mcp, or
cargo build --release --manifest-path mcp/Cargo.toml, and the program is then
mcp/target/release/forthling-mcp. With Claude Code:
claude mcp add forthling -- forthling-mcp
Other clients start it the same way: the command forthling-mcp, over stdio.
When a client connects, the server tells the model the basics in its instructions: the
idioms that trip models up, locals rather than ROT, PICK and ROLL, the JSON words and
the limits. llms.txt says the same at more length, for a model that reads
it beforehand; a test keeps the limits in both the same.
Tools
| Tool | Arguments | |
|---|---|---|
forth_eval |
code, data, files, trace |
runs Forth code; returns the output, the data and float stacks, and the error if there was one |
forth_stack |
the stacks, without running anything | |
forth_words |
the words defined in this session, the latest first | |
forth_help |
word |
the stack effect of a word, what it does, an example, and the word list it is in; for a name that is not defined, close names. Words of the session show the ( ) comment after their name |
forth_reset |
a new session: every definition, stack value, the data and the files are gone |
A line of code, and so a string in S", is at most 1024 characters. Larger input, such
as a JSON document, goes in data: the code reads it with DATA ( -- c-addr u ), which
gives a copy in ALLOCATEd memory (FREE it). The data stays for later calls until a
call sends other data, and may be at most as large as the Forth memory:
{"name": "forth_eval", "arguments": {"code": "ALSO JSON DATA JSON-LENGTH .", "data": "[[59],[73,41]]"}}
Each session has files of its own, in memory and never on the disk: INCLUDE, REQUIRE,
the FILE words and the block words use them, and they stay until forth_reset. files
puts files there before the code runs, as an object of names and texts, replacing files of
the same name; so an agent can give a library once and INCLUDE it, and what the code
writes, a later call can read. The files take at most 4 MiB in all; a write past that
fails with the word's ior, and files that do not fit are refused.
{"name": "forth_eval", "arguments": {"code": "INCLUDE square.fs 7 SQUARE .", "files": {"square.fs": ": SQUARE DUP * ;"}}}
Each result is text the way the REPL shows it:
2401 ok
stack: 1 2
and the same as structured JSON (structuredContent, with an outputSchema):
{"output": "2401 ", "stack": [1, 2], "fstack": [], "compiling": false, "error": null, "steps": …, "max_depth": …}; steps and max_depth (only for forth_eval) tell how
many steps the call took and how deep the data stack went, counting the words of the
system it ran (. is written in Forth, so it counts too).
An error empties the stacks, so the result also tells what they held at the error, where it happened and which words were running; the model can put it right in one go:
error -10: division by zero
at input, line 2, column 3: MAIN
in: MAIN > STEP > /
stack at the error: 5 1
stack: empty
and as JSON: "error": {"code": -10, "message": "division by zero", "stack": [5, 1], "fstack": [], "words": ["MAIN", "STEP", "/"], "source": "input", "line": 2, "column": 3, "token": "MAIN", …}, with isError true. A word that took its arguments before it
failed, such as / here, has taken them. An undefined word that is in a word list
outside the search order gets a hint, which the text adds after the word:
error -13: undefined word: JSON@ (it is in the word list JSON; ALSO JSON finds it).
A runaway program can leave a hundred thousand cells on the stack, or as many words
running (endless recursion). The result then keeps the top 32 cells and the innermost 32
words, the text says ... (n more) and the JSON has the full depth in stack_depth,
fstack_depth and words_depth. A definition that is still open (compiling true)
says so in the text: compiled (a definition is still open; ; ends it).
When the code ran T{ ... -> ... }T tests (ALSO TESTING), the result also has the counts
of that call, and the text starts with tests: 1 passed, 1 failed. The failure lines
(FAIL input:3 (sums): incorrect result: expected <1> 3, got <1> 2) are in the output.
In JSON: "tests": {"passed": 1, "failed": 1, "failures": [{"source": "input", "line": 3, "group": "sums", "expected": [3], "expected_depth": 1, "actual": [2], "actual_depth": 1, "stack": [], "expected_floats": [], "expected_floats_depth": 0, "actual_floats": [], "actual_floats_depth": 0}], "failures_dropped": 0}. The first 32 failures are kept, and each
list keeps its top 32 cells and floats (the depths tell how many there were). A file given with files
shows its name as source.
What an agent sees for typical mistakes
Each case was run through forth_eval (#47); the answer is the first lines of the text.
The code was run from a fresh session.
| Mistake | Code | Answer |
|---|---|---|
| undefined word | 1 2 FOO . |
error -13: undefined word: FOO, the column, the stack at the error 1 2 |
| word in a word list not in the search order | S" :memory:" DB-OPEN |
error -13: undefined word: DB-OPEN (it is in the word list SQLITE; ALSO SQLITE finds it) |
| undefined word in a definition | : sq DUPP * ; |
error -13: undefined word: DUPP, at its column |
| stack underflow | : add2 + ; 1 add2 |
error -4: stack underflow, in: ADD2 > +, the stack at the error |
| word that eats too much | : f ( n -- ) DROP ; f |
error -4, in: F > DROP |
IF, DO, BEGIN outside a definition |
1 IF 2 THEN |
error -14: interpreting a compile-only word: IF |
unclosed IF |
: foo 1 IF 2 ; |
error -22: control structure mismatch, at the ; |
LOOP without DO |
: f LOOP ; |
error -22: control structure mismatch |
| unclosed definition | : foo 1 2 + |
compiled (a definition is still open; ; ends it) |
| division by zero | 1 0 / |
error -10: division by zero, in: /, stack at the error empty (/ took its arguments) |
| bad address | 12345678 @ |
error -9: invalid memory address: 12345678 |
| step limit | : spin BEGIN 1 DROP AGAIN ; spin |
error -258: limit exceeded: steps, in: SPIN > DROP |
| output limit | : p BEGIN 65 EMIT AGAIN ; p |
the output up to the limit, then error -258: limit exceeded: output |
| endless stack growth | : grow BEGIN 1 AGAIN ; grow |
error -3: stack overflow, the top 32 cells and ... (n more) |
| endless recursion | : r RECURSE ; r |
error -5: return stack overflow, the innermost 32 words |
| missing file | S" nofile.fth" INCLUDED |
error -38: non-existent file: nofile.fth: no such file |
error inside EVALUATE |
S" 1 2 FOO" EVALUATE |
at evaluate, line 1, column 5: FOO, stack 1 2 |
| line over 1024 characters | S" xxxx…" TYPE |
error -18: parsed string overflow: input line too long |
ABORT" |
: chk 0= ABORT" zero" ; 0 chk |
error -2: aborted: zero |
CATCH |
: t 1 0 / ; : u ['] t CATCH . ; u |
prints -10, no error result |
What gives no error, and so no message: an unclosed S" or ( takes the rest of the
line (as the standard says); : f >R ; leaves the return stack unbalanced and 1 f
returns without a word; ALLOCATE of a negative size and FREE twice answer with a
non-zero ior on the stack (-59, -60), and so does a failed DB-EXEC (-261); a
JSON path that is not there gives 0 0 0. These follow the standard or the word's
stack effect; the agent must read the stack.
With "trace": true, forth_eval also returns a trace: each word that ran, with how deep
it was nested and the data stack when it started (at most its top 8 cells), at most 1000
words; trace_dropped counts the rest. The insides of the system's own words are left
out. The text starts with it, indented the way TRACE-ON prints it:
trace:
F <0>
SQ <1> 3
DUP <1> 3
* <2> 3 3
1+ <1> 9
. <1> 10
end of trace
10 ok
stack: empty
and the JSON has "trace": [{"word": "F", "depth": 0, "stack": [], "stack_depth": 0}, {"word": "SQ", "depth": 1, "stack": [3], "stack_depth": 1}, …], "trace_dropped": 0. The
trace of a call that fails shows how it got to the error. In the code itself,
ALSO DEBUG TRACE-ON … TRACE-OFF prints the same lines as output.
BREAK (also ALSO DEBUG) marks a place to look at. It does not stop the program, since
no one could answer in the middle of a call; instead the result has breaks, what the
program looked like at each BREAK (at most 100; breaks_dropped counts the rest), with
the same fields as an error: stack, fstack, words, source, line, column and
token. The text starts with a line for each:
break 1: in F > BREAK, at input, line 1, column 3: stack <2> 7 9
ALSO TUTORIAL gives the tutorial: 20 lessons of Forth, ten for beginners and ten
beyond, that an agent can walk a person through (LESSONS, n LESSON, CHECK tests the
answer, HINT, NEXT).
The JSON words are installed (ALSO JSON), and the SQLite words for databases in memory
(ALSO SQLITE, only :memory:, which SQL stops when the time is up and which cannot
grow larger than the Forth memory) and the regular expression words (ALSO REGEX, which
match in linear time) and the vector, matrix, linear algebra and special function words (ALSO SCIENCE); without the Cargo features sqlite, regex and science
(--no-default-features) the server is built without them.
The HTTP words (ALSO HTTP, see http/README.md) are a third feature,
http, which is off by default because it reaches the network. Build the server with it
(cargo install forthling-mcp --features http) and start it with the hosts that Forth code
may send requests to, once for each host: forthling-mcp --allow-host api.example.com
(*.example.com and * also work). Without --allow-host the network stays closed and the
model is not told about the words. It is the only option that opens something outside the
sandbox, and only for the hosts you name; a Forth word cannot add one.
The sandbox
Every session runs in forthling's sandbox: files only in memory, and each call at most 10 million steps, 5 seconds and 1 MiB of output; the session's definitions and the like at most 4 MiB in all. The options change these limits, each up to a ceiling the program fixes:
-m, --memory SIZE Forth memory (default 1M) [64M]
--max-steps N steps per call (default 10000000) [1000000000]
--max-time T time per call, such as 5s or 500ms (default 5s) [60s]
--max-output SIZE output per call (default 1M) [16M]
--max-space SIZE definitions and the like in all (default 4M) [64M]
--allow-host HOST a host that Forth code may send HTTP requests to (repeat)
There is no option to switch the sandbox off or to permit files, so changing how the
server is started does not open them either. Only --allow-host opens the network, for
the hosts it names (see above).
What enforces it. The sandbox is enforced by the server, not by what the model is
told or promises: the tools take only Forth code (other arguments are refused), and no
Forth word can change a limit or a permission. A user who asks the AI to get around the
sandbox cannot do it through forthling. An agent that also has other tools, such as a
shell or editing files, can however go around it: change the MCP configuration, or start
another program. Against that, forthling cannot help; use the permissions of the agent
instead. In Claude Code: deny or limit the shell, deny edits to the MCP configuration
(.mcp.json, ~/.claude.json), and allow only the MCP servers you want through managed
settings. For extra safety against a bug in forthling, run the server in a container or
as a user with few rights.
Testing
cargo test --manifest-path mcp/Cargo.toml
cargo test --manifest-path mcp/Cargo.toml --no-default-features
cargo test --manifest-path mcp/Cargo.toml --all-features
Links
- Source and the rest of forthling: https://github.com/DeSchaker/forthling
- The MCP Registry knows this server as
io.github.DeSchaker/forthling(the line below lets it check that the crate is ours). - mcp-name: io.github.DeSchaker/forthling
forthling MCP questions
What tools does forthling MCP provide?
It exposes 5 tools, including forth_eval, forth_stack, forth_words, forth_help, forth_reset.
How does the session state work?
The agent maintains a single session where defined words and stacks persist between calls until a reset is performed.
Can I use files with forthling?
Files are handled in-memory and never written to disk; they persist until the session is reset.
Is the environment secure?
Yes, it runs in a sandbox with limits on memory, execution steps, time, and output size.