Repository navigation
Initial GRASS MCP architecture for active GRASS sessions - #6
Open
lindakarlovska wants to merge 1 commit into
Open
lindakarlovska wants to merge 1 commit into
lindakarlovska wants to merge 1 commit into
Conversation
…GRASS session with the limitation for a few GRASS tools
lindakarlovska
force-pushed
the
setting-up--grass-mcp-architecture
branch
from
November 20, 2026 12:52
3740807 to
1d57bc1
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The main idea of this PR is to put together the first solid skeleton of GRASS MCP so it is easy to run, test in real life (mainly through OpenCode), and build on further. It is not a universal session manager yet for multiple independent sessions. Right now it works only inside one active GRASS session.
I tried to keep responsibilities separated. There is a tools folder with high-level functions like get_project_context, list_raster_maps, list_vector_maps, get_current_region etc. At the same time, it includes mapping to other GRASS tools, so we do not need to hand-write schemas for every single GRASS module.
At the moment, all high-level tools should be available. Standard module tools are intentionally limited to raster and vector tools, and only a small subset for now. I do not think it makes sense to add much more at this stage; first we should tune and stabilize what is already here.
Testing is easiest in OpenCode, because you can launch it directly from an active GRASS session terminal, so it already has GRASS environment variables.
You can run it like this:
grass-mcp.python -c "from importlib.metadata import version; print(version('mcp'))"The version should match the range pinned in
pyproject.toml.grass-mcp.You can put this config either in your project as
opencode.json(projectscope) or globally as
~/.config/opencode/opencode.json.Example config:
{ "$schema": "https://opencode.ai/config.json", "mcp": { "grass": { "type": "local", "command": ["/absolute/path/to/venvs/grass-mcp/bin/grass-mcp"] } } }What GRASS session is currently active?. If the response containsgisdbase,location, andmapset, and more info about projection - the setup is correct. (It should run get_session_info and get_project_context grass-mcp functions internally).I think it is a good idea to keep GRASS MCP tied to a specific MCP version and run it from a dedicated virtual environment.
For me, this made setup much easier: create venv, run python -m pip install -e ., done.
I found out that the python mcp library (https://pypi.org/project/mcp/) can differ a lot between versions and can be incompatible. Code that worked for 2.2.0 did not work in 2.3.0. So instead of users having random mcp versions and hitting confusing breakage, I think a virtualenv-based setup is safer. That said, I am open to better ideas if someone has one. I just think one good follow-up from this PR is agreeing on the long-term distribution strategy.
Originally, this code came from my repo:
https://github.com/lindakarlovska/grass-mcp-my.git
Some known issues are described there (if people follow the steps above, they should usually avoid them).
After playing a bit (and more) with existing MCPs at work (Gitea, Oracle, PostgreSQL) I realized that GRASS MCP could fasten my work with GRASS - so I first sketched the architecture on paper over the summer. Later, in my free time, I discussed different options with ChatGPT. Once I was happy with the direction, I iterated with GPT-5.3-Codex and guided the implementation step by step. I reviewed every line and tested the functionality with prompts in OpenCode. I’m also attaching a few screenshots from testing:
I’d really appreciate a review, testing, and a critical perspective.:-)