tinymcp

tinymcp is an MCP server that runs locally and exposes device functionality on Golioth via the MCP protocol. It bridges LLM-based control with real device actions by leveraging Golioth’s LightDB State and Remote Procedure Calls (RPCs). RPCs defined in LightDB State can be exposed as MCP tools, enabling an LLM or agents to invoke device capabilities without modifying firmware. You’ll primarily interact with two components: the local tinymcp server and the remote Golioth-hosted RPCs that represent device actions like LED control or other RPC-enabled features. Tools appear as MCP endpoints, and you can test them using MCP Inspector, Claude Code, or Gemini CLI to verify the available RPCs before integrating with an assistant.

Once running, the server reads your Golioth project and device identifiers and uses your API key to communicate with the Golioth Management API. RPCs registered in the state schema become accessible to MCP clients, meaning you can trigger actions on the device (via RPCs) from an LLM or automation tool. If you don’t yet have a device on Golioth, the included blinky example demonstrates exposing a simple LED control RPC to the MCP surface so you can experiment with LLM-driven control end-to-end.

Prerequisites:

• Go installed (https://golang.org/dl/)
• Git
• Access credentials for your Golioth project (TINYMCP_PROJECT, TINYMCP_DEVICE, TINYMCP_API_KEY)

Install steps:

1. Clone the repository: git clone https://github.com/your/repo-url.git cd repo-name

2. Ensure Go modules are up to date: go mod download

3. Build or run the tinymcp server locally: Build to a binary named tinymcp: go build -o tinymcp ./server

   Run directly: go run ./server

4. Set the required environment variables (example): export TINYMCP_PROJECT=your-golioth-project-id export TINYMCP_DEVICE=your-golioth-device-id export TINYMCP_API_KEY=your-api-key

5. Verify the server starts and is reachable at the expected port (default may be localhost:8080, as referenced by MCP Inspector and tools).

Notes:

• If you prefer not to build, you can run the server with go run ./server, which compiles and runs in one step.
• The exact port or binding can be configured in the server code or environment; adjust as needed for your environment.

Tips and considerations:

• The tinymcp server relies on Golioth management APIs; ensure your API key has appropriate permissions for the project and device.
• RPCs exposed via LightDB State depend on how you’ve defined the schema under mcp/tools/schema. If you don’t see tools, verify that your RPCs are correctly registered in LightDB State and that the tinymcp server can access them.
• The blinky example is a convenient starter for testing; follow its documentation to expose a simple LED RPC and then test through MCP tools.
• When using MCP Inspector, point it at http://localhost:8080 (or the port you’re using) and use List Tools to view RPCs.
• For Claude Code or Gemini CLI integrations, use the commands in the README to connect to the local tinymcp server and ensure the transport parameters (such as the server URL) are correct.
• Environment variables are sensitive; avoid leaking TINYMCP_API_KEY in logs or shared configurations.