shinkuro

Shinkuro is a Python-based MCP server that loads Markdown prompt files from a local folder or a Git repository and exposes them as MCP Prompts. It acts as a universal prompt loader, allowing you to organize prompts in folders or remote repos and serve them through MCP-enabled clients. The server offers a CLI interface to configure what folder to read from, whether to pull updates from a Git source, and how to format template variables, making it convenient to reuse prompts across teams and environments. You can run Shinkuro via the uvx runner, pointing it at the shinkuro command, and supply environment variables to point to your prompts source.

Usage scenarios include local file prompts (point FOLDER at a directory of markdown files), or remote Git-backed prompts (set GIT_URL and FOLDER to a subfolder within the repo). You can also integrate with Spec-Kit prompts by arranging your prompts in a .shinkuro/prompts folder or a configured subfolder and adjusting environment variables (e.g., VARIABLE_FORMAT, AUTO_DISCOVER_ARGS, SKIP_FRONTMATTER) to tailor how prompts are surfaced to clients.

Prerequisites:

• Python 3.8+ (preferably latest 3.x stable)
• PIP (comes with Python)
• Optional: git (for cloning remote repos via GIT_URL)

Install the Shinkuro MCP server from PyPI:

python -m pip install shinkuro

Verify installation:

uvx --version  # or shinkuro --version if exposed directly

Run the server using uvx (as shown in the README):

uvx shinkuro

Configure the server via environment variables as needed when starting the process, for example:

export FOLDER=/path/to/prompts
export GIT_URL=https://github.com/owner/repo.git       # optional for remote prompts
export CACHE_DIR=~/.shinkuro/remote
export AUTO_PULL=true
uvx shinkuro

If you prefer a single-step install and execution, you can also use pipx:

python -m pip install --user pipx
pipx ensurepath
pipx install shinkuro
pipx run shinkuro

Notes and tips:

• This Python implementation of Shinkuro is deprecated in favor of the Rust version. If possible, consider migrating to the Rust implementation for better performance and long-term support.
• The MCP server exposes prompts by scanning Markdown files in the configured FOLDER (including nested folders). Each file becomes a separate prompt; you can name prompts via frontmatter or derive from filenames.
• Environment variables: FOLDER or GIT_URL are required to point to your sources. GIT_URL enables cloning remote repositories into a local cache (CACHE_DIR). AUTO_PULL can refresh local copies on startup. VARIABLE_FORMAT controls template variable syntax (brace or dollar).
• Private repositories are supported when GIT_URL includes credentials or SSH configuration.
• For Spec-Kit workflows, place spec-kit prompts under the configured prompts folder (e.g., ./.shinkuro/prompts) and adjust environment vars (e.g., SKIP_FRONTMATTER, AUTO_DISCOVER_ARGS) to match your needs.
• If you run into issues with cloning or permissions, verify that the environment running uvx/shinkuro has network access and the necessary SSH keys or credentials for private repos.