Babashka MCP Server

A Model Context Protocol server for interacting with Babashka, a native Clojure interpreter for scripting.

Features

Execute Babashka code through MCP tools
Cache recent command results
Access command history through MCP resources
Configurable command timeouts

Prerequisites

Install Babashka

Babashka can be installed in several ways:

macOS

brew install borkdude/brew/babashka

Linux

bash < <(curl -s https://raw.githubusercontent.com/babashka/babashka/master/install)

Windows

# Using scoop
scoop install babashka

For other installation methods, see the official Babashka installation guide.

Verify Installation

After installation, verify Babashka works:

# Check version
bb --version

# Try a simple expression
bb -e '(+ 1 2 3)'

# Run a script from string
bb -e '(defn hello [x] (str "Hello, " x "!")) (hello "World")'

# Use -i flag to process lines of input
ls | bb -i '(take 2 *input*)'

Installation

# Install dependencies
npm install

# Build the MCP server
npm run build

Configuration

The server can be configured through environment variables:

BABASHKA_PATH: Path to the Babashka executable (default: "bb")

Tools

execute

Execute Babashka code with optional timeout:

{
  name: "execute",
  arguments: {
    code: string;      // Babashka code to execute
    timeout?: number;  // Timeout in milliseconds (default: 30000)
  }
}

Example:

{
  name: "execute",
  arguments: {
    code: "(+ 1 2 3)",
    timeout: 5000
  }
}

Resources

The server maintains a cache of recent command executions accessible through:

babashka://commands/{index} - Access specific command results by index

Babashka Language Features

Tail Call Optimization (TCO)

Babashka supports explicit tail call optimization through the recur special form, but does not implement automatic TCO. For example:

;; This will cause stack overflow
(defn countdown [n]
  (if (zero? n)
    :done
    (countdown (dec n))))

;; This works with TCO using recur
(defn countdown [n]
  (if (zero? n)
    :done
    (recur (dec n))))

Useful Resources

Official Resources

Babashka GitHub Repository - The main Babashka project
Babashka Book - Official documentation
Babashka Examples - Collection of example scripts

Community Tools & Libraries

pod-babashka-buddy - Cryptographic API for Babashka
bb-clis - Collection of useful Babashka CLI scripts
bb-scripts - Various utility scripts for Babashka

Development Tools

setup-babashka - GitHub Actions for installing Babashka
babashka-docker-action - Run Babashka scripts in GitHub Actions

Development

This server is designed to eventually become self-hosting, meaning it will be rewritten in Babashka itself. The current TypeScript implementation serves as a reference and starting point.

Roadmap

Self-Hosted Implementation
- Rewrite the MCP server in Babashka
- Leverage Babashka's native capabilities for better performance
- Remove Node.js dependency
- Maintain full compatibility with MCP protocol
- Support all current features:
  - Command execution
  - Resource management
  - Command history
  - Timeout handling
Enhanced Features
- Add support for Babashka pods
- Implement file watching capabilities
- Add REPL integration
- Support for multiple Babashka instances
Performance Optimizations
- Implement caching strategies
- Optimize resource usage
- Reduce startup time
Testing & Documentation
- Comprehensive test suite
- API documentation
- Usage examples
- Performance benchmarks