Kura - MCP 9P Server

An MCP (Model Context Protocol) server that provides tools for interacting with 9P (Plan 9 Filesystem Protocol) servers. This enables AI assistants like Claude to read, write, list, stat, touch, and remove files on remote 9P servers with security-first configuration.

Features

• Security-first: Configuration acts as a whitelist - only explicitly configured servers can be accessed
• Transport support: TCP (tcp:host:port or 9p://host:port) and Unix sockets (unix:/path)
• Timeout handling: Configurable connection and operation timeouts
• Six core tools: read, write, ls, stat, touch, rm
• Touch with mtime updates: Uses 9P wstat to update modification times
• Flexible configuration: Command-line config file specification or automatic discovery

Installation

From source

git clone <repository-url>
cd kura
make build

The binary will be placed in bin/kura-mcp.

Using Go directly

go install git.lan.thwap.org/thwap/kura/cmd/kura-mcp@latest

Configuration

Kura uses a YAML configuration file as a security whitelist. Only servers explicitly configured can be accessed.

Configuration Search Order

1. Command-line argument: kura-mcp --config /path/to/config.yaml
2. kura.yaml or kura.yml in current directory
3. $HOME/.config/kura/config.yaml or .yml
4. /etc/kura/config.yaml or .yml

Example Configuration

See kura.yaml for a full example. Minimal configuration:

targets:
  local-9p:
    address: "localhost:564"
    transport: "tcp"  # optional, inferred from address
    username: "none"
    timeout: 30  # seconds

Configuration as Whitelist

The configuration file acts as a security whitelist. Requests to connect to servers not listed in the configuration will be rejected with an error.

Usage with MCP

Add the server to your MCP client configuration (e.g., Claude Desktop, Continue).

Example configuration for Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "kura": {
      "command": "/path/to/kura-mcp",
      "args": ["--config", "/path/to/kura.yaml"]
    }
  }
}

Or rely on automatic configuration discovery:

{
  "mcpServers": {
    "kura": {
      "command": "/path/to/kura-mcp"
    }
  }
}

Tool Reference

All tools accept the following common arguments:

• transport (string, required): Either "tcp" or "unix"
• address (string, required): For TCP: "host:port" (e.g., "localhost:564"). For Unix: socket path (e.g., "/var/run/9p.sock")
• path (string, required): File or directory path on the 9P server

read

Reads the entire contents of a file.

Example: "Read /etc/motd from the 9P server at localhost:564"

write

Writes data to a file.

Additional argument:

• content (string, required): Data to write

Example: "Write 'hello' to /tmp/test.txt"

ls

Lists directory contents.

Example: "List files in /home/user"

stat

Retrieves file metadata (size, permissions, timestamps, etc.).

Example: "Get stats for /etc/passwd"

touch

Ensures a file exists, creating it if necessary. Updates file modification time using 9P wstat when possible.

Example: "Create empty file /tmp/flag"

rm

Removes a file or empty directory.

Example: "Delete /tmp/oldfile"

Security Model

Kura implements a security-first approach:

1. Whitelist only: Only servers explicitly configured in targets section can be accessed
2. Configuration validation: Each request is validated against the configuration before any network connection is made
3. No default access: There is no "allow all" mode; explicit configuration is required
4. Transport parsing: Addresses are parsed and validated before use

Development

Building

make build

Testing

make test

Running locally

make run

Code Quality

The project includes comprehensive unit tests for configuration, transport parsing, and tool logic. Run all tests with:

go test ./...

Pre-commit Hooks

The repository includes a pre-commit configuration for automated code quality checks. To set it up:

1. Install pre-commit:

   pip install pre-commit
   # or using brew: brew install pre-commit
   # or using conda: conda install -c conda-forge pre-commit
   

2. Install the git hooks:

   pre-commit install
   pre-commit install --hook-type commit-msg  # optional: commit message validation
   

3. Run hooks manually on all files:

   pre-commit run --all-files
   

The hooks include:

• Go formatting: gofmt and goimports
• Go linting: golangci-lint with staticcheck, govet, gosec, etc.
• Go module tidiness: go mod tidy
• Go unit tests: Runs tests on changed packages
• YAML validation: Checks configuration files
• Makefile linting: Validates Makefile syntax
• General file checks: trailing whitespace, end-of-file fixes, etc.

License

MIT

Acknowledgements

• Uses go9p for 9P protocol implementation
• Uses mcp-go for MCP server framework
• Inspired by Plan 9 from Bell Labs and the 9P protocol