shaarli-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| PORT | No | HTTP port. Default 3000. | 3000 |
| SHAARLI_URL | Yes | Required. Origin only, http or https, with no userinfo, query, hash, or path. Example: http://127.0.0.1:8097. A URL whose path is already /api/v1 is rejected. | |
| MCP_TRANSPORT | No | Transport mode: stdio or http. The --http command-line option overrides this. | |
| SHAARLI_CONTACT | No | Contact token in the User-Agent. Must not contain the API secret. | |
| SHAARLI_API_SECRET | Yes | Required. HMAC key for per-request JWTs. This is the value from Shaarli administration, not a session cookie. Redacted in logs, errors, and tool results. | |
| SHAARLI_PER_MINUTE | No | Local request budget. Default 30. Cache hits do not spend it. | 30 |
| SHAARLI_TIMEOUT_MS | No | Upstream timeout. Default 20000. | 20000 |
| SHAARLI_ALLOW_WRITES | No | Must be the literal true before a confirmed write is sent. The string "true" in tool input is rejected; this environment variable enables writes when set to true. | |
| SHAARLI_CACHE_TTL_SEC | No | Read cache TTL. Default 60. Writes clear the cache. | 60 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| shaarli_linksA | Search, get, create, update, and delete Shaarli links. Search uses searchterm, searchtags, visibility, offset, and limit. GET /api/v1/links and GET /api/v1/links/{id}. Writes need confirm true and SHAARLI_ALLOW_WRITES=true. PUT /links/{id} replaces the whole link, so update fetches the existing link and merges the fields you pass. Omit confirm for a dry-run preview. Actions: search, get, create, update, delete. |
| shaarli_tagsA | List, get, rename, and delete Shaarli tags. GET /api/v1/tags and GET /api/v1/tags/{tagName}. Rename is PUT with body name. Delete removes the tag from every bookmark. Writes need confirm true and SHAARLI_ALLOW_WRITES=true. Omit confirm for a dry-run preview. Actions: list, get, rename, delete. |
| shaarli_infoB | Read Shaarli instance info and history. GET /api/v1/info and GET /api/v1/history. History accepts since, offset, and limit. Actions: info, history. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 3 tools
The three tools are cleanly separated by resource: instance info/history, links, and tags. Each tool's description enumerates its actions, so an agent can easily pick the right tool and action without overlap.
All tools follow a consistent shaarli_<resource> pattern in snake_case, with plural resource nouns where appropriate. The convention is predictable and easy to remember.
Three tools is well-scoped for a Shaarli API wrapper, grouping operations by resource rather than exposing dozens of tiny endpoints. Each tool earns its place and covers a distinct domain area.
The surface covers the main lifecycle: info/history, full link CRUD plus search, and tag list/get/rename/delete. Minor gaps like explicit tag creation or additional link metadata operations are small and can be worked around.