easybill-mcp 1.0.1 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +175 -62
  2. package/package.json +12 -1
package/README.md CHANGED
@@ -1,7 +1,9 @@
1
1
  # easybill MCP Server
2
2
 
3
3
  An [MCP](https://modelcontextprotocol.io) server for the [easybill REST API](https://www.easybill.de/api/).
4
- Gives Claude access to your invoices, customers, article catalogue, payments, projects and tracked time.
4
+ Gives any MCP-capable assistant — Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Zed,
5
+ Codex CLI, Gemini CLI, Cline — access to your invoices, customers, article catalogue, payments,
6
+ projects and tracked time.
5
7
 
6
8
  Built on the official [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk)
7
9
  (TypeScript), talking stdio.
@@ -22,118 +24,229 @@ Built on the official [`@modelcontextprotocol/sdk`](https://github.com/modelcont
22
24
 
23
25
  In easybill: **Einstellungen → App-Center → API**. Create a key and copy it.
24
26
 
25
- ### 2. Build
27
+ ### 2. Register it with your client
28
+
29
+ This is a plain stdio MCP server published on npm, so any MCP client can run it with `npx` —
30
+ no clone, no build, no global install:
26
31
 
27
32
  ```bash
28
- git clone https://github.com/stack74/easybill-mcp.git
29
- cd easybill-mcp
30
- npm install
31
- npm run build
33
+ npx -y easybill-mcp
32
34
  ```
33
35
 
34
- ### 3. Test locally first
36
+ Configuration is entirely through environment variables (full list under
37
+ [Configuration](#configuration)). Two matter now:
35
38
 
36
- Copy `.env.example` to `.env`, put your key in it, then run the read-only self-test:
39
+ - Leave `EASYBILL_ENABLE_WRITES` unset to start **read-only**.
40
+ - Set `EASYBILL_RATE_LIMIT_PER_MINUTE` to **10** on easybill's PLUS plan or **60** on BUSINESS.
41
+
42
+ Most clients use the same JSON shape under an `mcpServers` key:
43
+
44
+ ```json
45
+ {
46
+ "mcpServers": {
47
+ "easybill": {
48
+ "command": "npx",
49
+ "args": ["-y", "easybill-mcp"],
50
+ "env": {
51
+ "EASYBILL_API_KEY": "your_api_key_here",
52
+ "EASYBILL_RATE_LIMIT_PER_MINUTE": "10"
53
+ }
54
+ }
55
+ }
56
+ }
57
+ ```
58
+
59
+ Where that block goes:
60
+
61
+ | Client | Config location |
62
+ |---|---|
63
+ | **Claude Desktop** | Settings → Developer → Edit Config, or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) · `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
64
+ | **Cursor** | `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project) |
65
+ | **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
66
+ | **Cline / Roo Code** | MCP Servers panel → Configure MCP Servers (`cline_mcp_settings.json`) |
67
+ | **Gemini CLI** | `~/.gemini/settings.json` |
68
+ | **Claude Code** | `claude mcp add`, see below |
69
+ | **VS Code / Copilot** | `.vscode/mcp.json`, different key — see below |
70
+ | **Zed** | `settings.json` → `context_servers`, see below |
71
+ | **Codex CLI** | `~/.codex/config.toml`, TOML instead of JSON — see below |
72
+
73
+ > **Windows:** if a client fails to start `npx`, use `"command": "cmd"` with
74
+ > `"args": ["/c", "npx", "-y", "easybill-mcp"]`.
75
+
76
+ #### Claude Code
37
77
 
38
78
  ```bash
39
- cp .env.example .env
40
- $EDITOR .env
41
- npm run smoke
79
+ claude mcp add easybill \
80
+ --env EASYBILL_API_KEY=your_api_key_here \
81
+ --env EASYBILL_RATE_LIMIT_PER_MINUTE=10 \
82
+ -- npx -y easybill-mcp
42
83
  ```
43
84
 
44
- It makes five read-only calls and prints what came back:
85
+ `claude mcp add` does not overwrite an existing entry — to change the environment later,
86
+ `claude mcp remove easybill -s local` first, then add it again.
87
+
88
+ #### VS Code (GitHub Copilot agent mode)
45
89
 
90
+ VS Code uses `servers`, not `mcpServers`, and can prompt for the key instead of storing it
91
+ in the file. Put this in `.vscode/mcp.json` (workspace) or open **MCP: Open User
92
+ Configuration**:
93
+
94
+ ```json
95
+ {
96
+ "inputs": [
97
+ { "id": "easybill_key", "type": "promptString", "description": "easybill API key", "password": true }
98
+ ],
99
+ "servers": {
100
+ "easybill": {
101
+ "type": "stdio",
102
+ "command": "npx",
103
+ "args": ["-y", "easybill-mcp"],
104
+ "env": {
105
+ "EASYBILL_API_KEY": "${input:easybill_key}",
106
+ "EASYBILL_RATE_LIMIT_PER_MINUTE": "10"
107
+ }
108
+ }
109
+ }
110
+ }
46
111
  ```
47
- easybill-mcp-server v1.x.y self-test
48
- API: https://api.easybill.de/rest/v1
49
- Throttle: 60 req/min | writes disabled
50
112
 
51
- OK Auth check (customer groups): total=2 first=Stammkunden
52
- OK Customers: total=42 first=Example GmbH
53
- OK Invoices: total=128 first=RE-2026-0001
54
- OK Unpaid invoices: total=7 first=RE-2026-0117
55
- OK Articles (positions): total=95 first=ART-001
113
+ #### Zed
56
114
 
57
- All probes passed. The server is ready to register with an MCP client.
115
+ In `settings.json`:
116
+
117
+ ```json
118
+ {
119
+ "context_servers": {
120
+ "easybill": {
121
+ "source": "custom",
122
+ "command": "npx",
123
+ "args": ["-y", "easybill-mcp"],
124
+ "env": {
125
+ "EASYBILL_API_KEY": "your_api_key_here",
126
+ "EASYBILL_RATE_LIMIT_PER_MINUTE": "10"
127
+ }
128
+ }
129
+ }
130
+ }
58
131
  ```
59
132
 
60
- (Numbers above are illustrative — you will see your own account's totals.)
133
+ #### Codex CLI
61
134
 
62
- On a bad key it fails on the first call and stops, so it never burns your rate limit.
135
+ In `~/.codex/config.toml`:
63
136
 
64
- To poke at individual tools interactively:
137
+ ```toml
138
+ [mcp_servers.easybill]
139
+ command = "npx"
140
+ args = ["-y", "easybill-mcp"]
141
+ env = { EASYBILL_API_KEY = "your_api_key_here", EASYBILL_RATE_LIMIT_PER_MINUTE = "10" }
142
+ ```
143
+
144
+ #### Hosted clients that only speak remote MCP
145
+
146
+ Some clients (ChatGPT connectors, hosted agent platforms) accept only HTTP/SSE endpoints, not
147
+ stdio. Bridge it locally:
65
148
 
66
149
  ```bash
67
- npm run inspect # MCP Inspector, loads .env
150
+ npx -y supergateway --stdio "npx -y easybill-mcp"
68
151
  ```
69
152
 
70
- > **Note:** `.env` is only read by these npm scripts, via Node's `--env-file`. The server
71
- > itself reads plain environment variables — when you register it with an MCP client, pass
72
- > the key through the client's config as shown below, not via `.env`.
153
+ Only do this if you understand the exposure: anything that reaches that endpoint reaches your
154
+ accounting data. Keep it bound to localhost or behind a tunnel with authentication, and never
155
+ run the bridge with writes enabled unless the endpoint is protected.
73
156
 
74
- ### 4. Register with Claude Code
157
+ ### 3. Verify the connection
75
158
 
76
- Read-only (recommended to start):
159
+ Ask the assistant to call `easybill_get_server_info`. It reports the mode, the limits and
160
+ whether easybill accepted the credentials:
77
161
 
78
- ```bash
79
- claude mcp add easybill \
80
- --env EASYBILL_API_KEY=your_api_key_here \
81
- --env EASYBILL_RATE_LIMIT_PER_MINUTE=10 \
82
- -- node /absolute/path/to/easybill-mcp/dist/index.js
162
+ ```json
163
+ {
164
+ "server_version": "1.0.1",
165
+ "writes_enabled": false,
166
+ "tools_registered": { "read_only": 28, "write": 0, "withheld_because_writes_disabled": 26 },
167
+ "rate_limit_per_minute": 10,
168
+ "connection": "ok — credentials accepted by easybill"
169
+ }
83
170
  ```
84
171
 
85
- With write access, once you trust it:
172
+ ### 4. Enable writes, once you trust it
173
+
174
+ Add `EASYBILL_ENABLE_WRITES=true` to the server's environment:
86
175
 
87
176
  ```bash
88
177
  claude mcp add easybill \
89
178
  --env EASYBILL_API_KEY=your_api_key_here \
90
179
  --env EASYBILL_RATE_LIMIT_PER_MINUTE=10 \
91
180
  --env EASYBILL_ENABLE_WRITES=true \
92
- -- node /absolute/path/to/easybill-mcp/dist/index.js
181
+ -- npx -y easybill-mcp
93
182
  ```
94
183
 
95
- Set `EASYBILL_RATE_LIMIT_PER_MINUTE` to **10** on the PLUS plan or **60** on BUSINESS.
184
+ The 26 write tools are registered at startup, so the change only takes effect once the client
185
+ restarts the server process — editing the config in a running session is not enough. Confirm
186
+ with `easybill_get_server_info`: `writes_enabled` must read `true`.
187
+
188
+ ---
189
+
190
+ ## Running from a local clone
96
191
 
97
- Verify it connected:
192
+ For development, or to run a version you have not published:
98
193
 
194
+ ```bash
195
+ git clone https://github.com/stack74/easybill-mcp.git
196
+ cd easybill-mcp
197
+ npm install
198
+ npm run build
99
199
  ```
100
- > use easybill_get_server_info
200
+
201
+ Then point the client at the built entry point instead of `npx` — `"command": "node"`,
202
+ `"args": ["/absolute/path/to/easybill-mcp/dist/index.js"]`, same `env` block. Or straight from
203
+ GitHub without cloning, which is slower because it compiles TypeScript on install via the
204
+ `prepare` script and needs a toolchain:
205
+
206
+ ```bash
207
+ npx -y github:stack74/easybill-mcp
101
208
  ```
102
209
 
103
- ### 5. Claude Desktop (alternative)
210
+ ### Test locally first
104
211
 
105
- Add to `claude_desktop_config.json`:
212
+ Copy `.env.example` to `.env`, put your key in it, then run the read-only self-test:
106
213
 
107
- ```json
108
- {
109
- "mcpServers": {
110
- "easybill": {
111
- "command": "node",
112
- "args": ["/absolute/path/to/easybill-mcp/dist/index.js"],
113
- "env": {
114
- "EASYBILL_API_KEY": "your_api_key_here",
115
- "EASYBILL_RATE_LIMIT_PER_MINUTE": "10"
116
- }
117
- }
118
- }
119
- }
214
+ ```bash
215
+ cp .env.example .env
216
+ $EDITOR .env
217
+ npm run smoke
120
218
  ```
121
219
 
122
- ### Installing without cloning
220
+ It makes five read-only calls and prints what came back:
123
221
 
124
- Once published to npm, no clone or build is needed — `npx` fetches and runs it:
222
+ ```
223
+ easybill-mcp-server v1.x.y self-test
224
+ API: https://api.easybill.de/rest/v1
225
+ Throttle: 60 req/min | writes disabled
125
226
 
126
- ```bash
127
- claude mcp add easybill --env EASYBILL_API_KEY=your_key -- npx -y easybill-mcp
227
+ OK Auth check (customer groups): total=2 first=Stammkunden
228
+ OK Customers: total=42 first=Example GmbH
229
+ OK Invoices: total=128 first=RE-2026-0001
230
+ OK Unpaid invoices: total=7 first=RE-2026-0117
231
+ OK Articles (positions): total=95 first=ART-001
232
+
233
+ All probes passed. The server is ready to register with an MCP client.
128
234
  ```
129
235
 
130
- Straight from GitHub also works, but is slower (it compiles TypeScript on install
131
- via the `prepare` script) and needs a toolchain:
236
+ (Numbers above are illustrative — you will see your own account's totals.)
237
+
238
+ On a bad key it fails on the first call and stops, so it never burns your rate limit.
239
+
240
+ To poke at individual tools interactively:
132
241
 
133
242
  ```bash
134
- claude mcp add easybill --env EASYBILL_API_KEY=your_key -- npx -y github:stack74/easybill-mcp
243
+ npm run inspect # MCP Inspector, loads .env
135
244
  ```
136
245
 
246
+ > **Note:** `.env` is only read by these npm scripts, via Node's `--env-file`. The server
247
+ > itself reads plain environment variables — when you register it with an MCP client, pass
248
+ > the key through the client's config, not via `.env`.
249
+
137
250
  ### Publishing to npm
138
251
 
139
252
  ```bash
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "easybill-mcp",
3
- "version": "1.0.1",
3
+ "version": "1.0.2",
4
4
  "description": "MCP server for the easybill REST API (invoices, customers, articles, payments, time tracking)",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -27,9 +27,20 @@
27
27
  },
28
28
  "keywords": [
29
29
  "mcp",
30
+ "mcp-server",
30
31
  "modelcontextprotocol",
31
32
  "model-context-protocol",
32
33
  "claude",
34
+ "claude-code",
35
+ "claude-desktop",
36
+ "cursor",
37
+ "vscode",
38
+ "copilot",
39
+ "windsurf",
40
+ "zed",
41
+ "codex",
42
+ "gemini-cli",
43
+ "cline",
33
44
  "easybill",
34
45
  "invoice",
35
46
  "invoicing",