Skip to content

Initial GRASS MCP architecture for active GRASS sessions - #6

Open
lindakarlovska wants to merge 1 commit into
OSGeo:mainfrom
lindakarlovska:setting-up--grass-mcp-architecture
Open

lindakarlovska wants to merge 1 commit into
OSGeo:mainfrom
lindakarlovska:setting-up--grass-mcp-architecture

Conversation

@lindakarlovska

Copy link
Copy Markdown

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:

  1. Create and activate a dedicated virtual environment.
cd /absolute/path/to/grass-mcp
python -m venv ~/venvs/grass-mcp
source ~/venvs/grass-mcp/bin/activate
python -m pip install -e .
  1. Check that MCP dependency was installed with grass-mcp.
python -c "from importlib.metadata import version; print(version('mcp'))"

The version should match the range pinned in pyproject.toml.

  1. Start a GRASS session in a terminal.
grass --text /path/to/grassdata/project/mapset
  1. In that same terminal, configure OpenCode to launch grass-mcp.

You can put this config either in your project as opencode.json (project
scope) 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"]
    }
  }
}
  1. Start OpenCode from the same terminal using standalone mode and verify the connection.
opencode --standalone
  1. Check the MCP connection to be green and ask the agent What GRASS session is currently active?. If the response contains gisdbase, location, and mapset, 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:

Screenshot from 2026-11-13 21-06-49 Screenshot from 2026-11-13 21-08-16 Screenshot from 2026-11-13 21-37-07

I’d really appreciate a review, testing, and a critical perspective.:-)

@lindakarlovska lindakarlovska added this to the 0.1.0 milestone Nov 13, 2026
@lindakarlovska lindakarlovska added the enhancement New feature or request label Nov 13, 2026
…GRASS session with the limitation for a few GRASS tools
@lindakarlovska
lindakarlovska force-pushed the setting-up--grass-mcp-architecture branch from 3740807 to 1d57bc1 Compare November 20, 2026 12:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant