planeshift-mcp
# planeshift-mcp
MCP server for Planeshift. It runs locally over stdio and forwards tool calls to the Planeshift Rails API (`/api/v1`).
## Install
Requires Node.js 20 or newer.
### 1. Log in (once)
```
npx -y planeshift-mcp login
```
Your browser opens Planeshift. Sign in, click Allow, and the token is saved to `~/.config/planeshift/credentials.json` (readable only by you). Claude Code and Claude Desktop both read it, so you only do this once. Use `--url https://your-instance` for a self-hosted Planeshift. `npx -y planeshift-mcp logout` revokes the token and deletes the file.
### 2a. Claude Code
```
claude mcp add --scope user planeshift -- npx -y planeshift-mcp
```
Start a new `claude` session and run `/mcp` to check that `planeshift` is connected.
### 2b. Claude Desktop
Open Settings > Developer > Edit Config (or edit `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows) and add the server:
```json
{
"mcpServers": {
"planeshift": {
"command": "npx",
"args": ["-y", "planeshift-mcp"]
}
}
}
```
Quit Claude Desktop completely and open it again. The tools appear under the tools icon of the chat box. If `npx` is not found, use the full path of `npx` (run `which npx`) as the `command`, since the app does not load your shell profile.
### Tools
`list_projects`, `get_timeline`, `add_note`, `add_meeting`, `add_todo_action`, `add_important_link`.
### Development mode
To use a local Planeshift (`http://localhost:3000`) without touching your production login, set `PLANESHIFT_ENV=development`, or pass `--dev` to the commands:
```
node src/index.js login --dev # saves ~/.config/planeshift/credentials.development.json
claude mcp add planeshift -e PLANESHIFT_ENV=development -- node /path/to/planeshift-mcp/src/index.js
```
For Claude Desktop, use `"command": "node"` with the full path to `src/index.js` and `"env": { "PLANESHIFT_ENV": "development" }`. Development mode keeps its own credentials file, and `--url` still overrides the address.
### Without `login`
Set `PLANESHIFT_URL` and `PLANESHIFT_TOKEN` (create a token on the API tokens page) in the `env` of the config above, or with `claude mcp add -e PLANESHIFT_URL=... -e PLANESHIFT_TOKEN=...`. They take precedence over the saved credentials.
## Development
```
npm install
npm start
```
Add a tool in `src/tools/` and register it in `src/index.ts`.
TDQS
Scored across 6 tools
The tools split cleanly into two reads (list_projects, get_timeline) and four distinct add_* writers targeting different artifacts (note, meeting, action, link). The only mild overlap is add_note vs add_meeting, since both append to the same timeline, but the descriptions clarify that meetings capture discussion/decisions.
All names are snake_case verb_noun (list_projects, get_timeline, add_note...), which is predictable and readable. Minor deviation: add_todo_action and add_important_link insert extra modifiers, making the noun phrase less uniform than the others.
Six tools is well-scoped for a project timeline server: two read operations plus four creation operations covering the domain's core entities. Every tool earns its place with no filler.
The surface covers listing, reading, and appending, but there is no way to update or delete notes/meetings/links, and notably no way to mark a to-do action as completed despite actions starting as pending. These gaps will force agents into dead ends for a to-do workflow.