mcpshim

Turn remote MCP servers into local command workflows.
A lightweight daemon + CLI bridge that centralizes MCP sessions, auth, discovery, and tool execution behind one local Unix socket.

Website · Repository · Quick Start · Core Commands

The Problem

Remote MCP servers are powerful, but each service has its own auth flow, transport expectations, and invocation patterns. Wiring all of that directly into every script or agent loop creates brittle command workflows.

For LLM agents, there is also context pressure: dumping raw MCP schemas for every connected server can consume prompt budget before useful work begins.

The Solution

mcpshimd handles MCP lifecycle concerns in one place: session management, discovery, retries, and OAuth flow.

mcpshim provides a stable CLI surface over a local Unix socket so tools can be called consistently, with dynamic flags translated to MCP arguments at runtime.

graph TD
		Agent["Your AI Agent / Script"]
		Agent -->|call| CLI["mcpshim CLI"]
		Agent -->|JSON request| Socket["Unix Socket"]
		CLI --> Socket
		Socket --> Daemon["mcpshimd"]
		Daemon --> MCP1["MCP Server: Notion"]
		Daemon --> MCP2["MCP Server: GitHub"]
		Daemon --> MCP3["MCP Server: Linear"]
		Daemon --> MCPN["..."]

Why mcpshim

Architecture

All client calls go through a Unix socket and JSON request/response protocol.

Source Layout

cmd/
	mcpshimd/             # Daemon entry point
	mcpshim/              # CLI entry point
configs/
	mcpshim.example.yaml  # Example configuration
internal/
	client/               # CLI command handling and IPC client logic
	config/               # Config loading and defaults
	mcp/                  # MCP transport + OAuth handling
	protocol/             # Request/response protocol types
	server/               # Daemon runtime and routing
	store/                # SQLite persistence

Quick Start

1. Install from source

go install github.com/mcpshim/mcpshim/cmd/mcpshimd@latest
go install github.com/mcpshim/mcpshim/cmd/mcpshim@latest

2. Configure

mkdir -p ~/.config/mcpshim
cp configs/mcpshim.example.yaml ~/.config/mcpshim/config.yaml

3. Start daemon and inspect

mcpshimd
mcpshim status
mcpshim servers
mcpshim tools

Path Defaults

All paths follow XDG defaults where applicable.

Daemon flags

Core Commands

Register MCP servers

mcpshim add --name notion --alias notion --transport http --url https://example.com/mcp
mcpshim set auth --server notion --header "Authorization=Bearer $NOTION_MCP_TOKEN"
mcpshim reload

Dynamic flags

Tool flags are converted automatically to MCP arguments:

mcpshim call --server notion --tool search --query "projects" --limit 10 --archived false

Tip: JSON output is automatic when stdout is not a terminal. Use --json to force JSON parsing behavior in interactive sessions.

OAuth Flow

For OAuth-capable MCP servers, you can configure URL-only registration:

mcpshim add --name notion --alias notion --transport http --url https://mcp.notion.com/mcp

When a request receives 401 and no Authorization header is configured, mcpshimd can initiate OAuth login, store tokens in SQLite (oauth_tokens), and retry automatically.

You can also pre-authorize:

mcpshim login --server notion
mcpshim login --server notion --manual

--manual supports cross-device auth by printing a URL and accepting pasted callback URL/code.

Call History

Every mcpshim call is recorded by mcpshimd with timestamp, server/tool, args, status, and duration.

mcpshim history
mcpshim history --server notion --limit 20
mcpshim history --server notion --tool search --limit 100

History is stored locally in SQLite (call_history table).

IPC Protocol

mcpshim communicates with mcpshimd over a Unix socket using JSON messages with an action field.

{"action":"status"}
{"action":"servers"}
{"action":"tools","server":"notion"}
{"action":"inspect","server":"notion","tool":"search"}
{"action":"call","server":"notion","tool":"search","args":{"query":"roadmap"}}
{"action":"history","server":"notion","limit":20}
{"action":"add_server","name":"notion","alias":"notion","url":"https://mcp.notion.com/mcp","transport":"http"}
{"action":"set_auth","name":"notion","headers":{"Authorization":"Bearer ..."}}
{"action":"reload"}

Lightweight Aliases

Generate shell functions:

eval "$(mcpshim script)"
notion search --query "projects" --limit 10

Install executable wrappers instead:

mcpshim script --install --dir ~/.local/bin
notion search --query "projects" --limit 10

See Also

Pantalk — Give your AI agent a voice on every chat platform. mcpshim gives your agent tools; Pantalk gives it a voice across Slack, Discord, Telegram, and more. Together they form a complete agent infrastructure stack.