getme-mcp-server

getMe MCP Server

An MCP server that exposes getMe key-value operations as Model Context Protocol (MCP) tools, enabling LLMs to talk to the getMe core database over HTTP via a Unix Domain Socket (UDS).

🔗 Quick Links

• GitHub Repository: AatirNadim/getMe
• PyPI Package: getme-mcp-server
• Core Database Docs: Architecture & Deep Dive
• DockerHub Image: getme
• Blog Part I - Building getMe: Read here!
• Blog Part II - Building getMe: Read here!

Using the MCP Server

The getme-mcp-server package is published on PyPI. For integration with MCP-compatible clients like Claude Desktop, Cursor, or the MCP Inspector, you can seamlessly run it using uvx or pipx.

Claude Desktop Configuration

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "getme": {
      "command": "uvx",
      "args": ["getme-mcp-server"],
      "env": {
        "GETME_SOCKET_PATH": "/tmp/getMeStore/sockDir/getMe.sock",
        "GETME_KEY_PREFIX": "agent-context:",
        "GETME_READ_ONLY": "false"
      }
    }
  }
}

Opencode Configuration

For Opencode, the MCP configuration format differs slightly from Claude. Add the following to your opencode.json (or ~/.config/opencode/opencode.json):

{
  "mcp": {
    "getme": {
      "type": "local",
      "command": ["uvx", "getme-mcp-server"],
      "env": {
        "GETME_SOCKET_PATH": "/tmp/getMeStore/sockDir/getMe.sock",
        "GETME_KEY_PREFIX": "agent-context:",
        "GETME_READ_ONLY": "false"
      }
    }
  }
}

Key differences from Claude:

• Uses "mcp" at the top level instead of "mcpServers".
• Requires "type": "local".
• The command is an array that includes both the executable and its arguments (e.g., ["uvx", "getme-mcp-server"]), whereas Claude separates them into "command" (string) and "args" (array).

Core Engine Lifecycle & Management

The MCP Server acts as a client bridge to the getMe database and does not manage the lifecycle of the core engine daemon.

• Manual Startup: If you manually start the getMe core engine, you are responsible for terminating it.
• Client/Agent Startup: If an MCP-compatible client (or an AI agent) runs an initialization script to start the database server, the daemon runs independently. When you close the MCP client, the getme-mcp-server process will cleanly terminate, but the getMe core engine daemon will continue running in the background. It falls on the user to manually terminate the daemon when it is no longer needed.

Features & Safety

• Read-Only Mode: Ensure LLMs don't mutate data via GETME_READ_ONLY=true.
• Destructive Operation Guards: The clear tool is disabled by default, ensuring agents can't accidentally drop the store.
• Payload & Connection Limits: Defends against massive payloads/batches and re-uses HTTP connections for performance.
• Prefix Isolation: Restrict the LLM to a specific namespace in the DB with GETME_KEY_PREFIX.
• Masked Logging: Tool execution metadata is logged, but payloads are masked to prevent leaking secrets.

Configuration (Environment Variables)

Control safety rules and performance via environment variables.

• GETME_SOCKET_PATH (default: /tmp/getMeStore/sockDir/getMe.sock): Path to the UNIX socket used by the core getMe daemon.
• GETME_READ_ONLY (default: false): If true, only get and get_json tools are registered.
• GETME_ALLOW_CLEAR (default: false): If true, enables the dangerous clear tool.
• GETME_KEY_PREFIX (default: ""): String prefix prepended to all keys. Sandboxes the LLM (e.g., agent1:).
• GETME_MAX_VALUE_SIZE_BYTES (default: 5242880 / 5MB): Limit on single value payload sizes.
• GETME_MAX_BATCH_ITEMS (default: 100): Maximum keys processed in one batch_put.

Best Practices

• Sandbox with Prefixes: Always use GETME_KEY_PREFIX when handing the database over to an LLM. For instance, using GETME_KEY_PREFIX="claude:" ensures the model can't overwrite core application data.
• Restrict Privileges: If the agent only needs context (e.g., fetching RAG documents or reading app state), enforce GETME_READ_ONLY=true.
• Never Allow Clear: Keep GETME_ALLOW_CLEAR=false (the default) in production environments to prevent catastrophic drops caused by hallucinated commands.
• Volume Mounts: Make sure the environment running the MCP server has adequate read/write permissions to the GETME_SOCKET_PATH.

Tools

Once connected, the LLM has access to the following operations:

• get(key) -> str
• get_json(key) -> object
• put(key, value) -> str
• put_json(key, json_value) -> str
• delete(key) -> str
• clear() -> str (Requires GETME_ALLOW_CLEAR=true)
• batch_put(pairs: object) -> object
• batch_get(keys: list) -> object
• batch_delete(keys: list) -> object

Development & Installation

Prereqs

• uv installed
• getMe core server running and listening on the Unix socket

Install from Source

cd mcp-server
uv sync

Fixing VS Code "package not installed" warnings

If Pylance shows warnings like Package "httpx" is not installed in the selected environment, VS Code is using a different Python interpreter than the uv virtualenv.

• Open Command Palette → Python: Select Interpreter
• Select: getMe/mcp-server/.venv/bin/python

This repo also includes a workspace setting that points the interpreter at mcp-server/.venv.

Run Locally

cd mcp-server
# optional override
export GETME_SOCKET_PATH=/tmp/getMeStore/sockDir/getMe.sock
uv run getme-mcp-server

Docker deployment

This MCP server speaks stdio (JSON-RPC), so when running in Docker you must avoid allocating a TTY.

Build the image:

cd mcp-server
docker compose build

Run it over stdio (recommended for MCP clients):

cd mcp-server
docker compose run --rm -T getme-mcp-server

The compose file bind-mounts the host UDS directory:

• host: /tmp/getMeStore/sockDir
• container: /tmp/getMeStore/sockDir

So the MCP server can reach the core getMe server via GETME_SOCKET_PATH=/tmp/getMeStore/sockDir/getMe.sock.