GistPad MCP

1# 📓 GistPad MCP
2 
3An MCP server for managing and sharing your personal knowledge, daily notes, and reuseable prompts via GitHub Gists. It's a companion to the GistPad [VS Code extension](https://aka.ms/gistpad) and [GistPad.dev](https://gistpad.dev) (for web/mobile), which allows you to access and edit your gists from any MCP-enabled AI product (e.g. GitHub Copilot, Claude Desktop).
4 
5- 🏃 [Getting started](#-getting-started)
6- 🛠️ [Included tools](#️-included-tools)
7- 📁 [Included resources](#-included-resources)
8- 💬 [Reusable prompts](#-reusable-prompts)
9- 💻 [CLI reference](#-cli-reference)
10 
11## 🏃 Getting started
12 
131. Using VS Code?
14   1. Install the [GistPad extension](https://aka.ms/gistpad) and then reload VS Code
15 
16      > _Note: This requires VS Code 1.101.0+, so if you're on an older version, it's time to upgrade!_
17 
18   1. Open the `GistPad` tab and sign-in with your GitHub account. After that, you can begin using GistPad from Copilot chat (in `Agent` mode) without doing any extra setup or token management 💪
19 
201. Other MCP clients...
21   1. Generate a personal access token that includes _only_ the `gist` scope: https://github.com/settings/tokens/new
22   1. Add the equivalent of the following to your client's MCP config file (or via an "Add MCP server" GUI/TUI):
23 
24      ```json
25      {
26        "mcpServers": {
27          "gistpad": {
28            "command": "npx",
29            "args": ["-y", "gistpad-mcp"],
30            "env": {
31              "GITHUB_TOKEN": "<YOUR_PAT>"
32            }
33          }
34        }
35      }
36      ```
37 
38Once your client it setup, you can start having fun with gists + MCP! 🥳 For example, try things like...
39 
401. **Exploring content**
41   - `How many gists have I edited this month?`
42   - `What's the summary of my <foo> gist?`
43 
441. **Creating content**
45   - `Create a new gist about <foo>`
46   - `Update my <foo> gist to call out <bar>`
47 
481. **Daily todos**
49   - `What are my unfinished todos for today?`
50   - `Add a new todo for <foo>`
51 
521. **Collaboration**
53   - `Add a comment to the <foo> gist saying <bar>`
54   - `Give me a share URL for the <foo> gist`
55   - `View my starred gists`
56 
571. **Gist organization**
58   - `Archive my gist about <foo>`
59   - `Add a new <foo> file to the <bar> gist and migrate the <baz> content into it`
60 
611. **Reusable prompts**
62   - `Create a new prompt that searches the web ofor a specified manga series and then provides a summary about it`
63   - `Delete my prompt about <foo>`
64 
65## 🛠️ Included tools
66 
67### Gist management
68 
69- `list_gists` - List all of your gists (excluding daily notes and archived gists).
70- `get_gist` - Get the contents of a gist by ID.
71- `create_gist` - Create a new gist with a specified description and initial file contents.
72- `delete_gist` - Delete a gist by ID.
73- `update_gist_description` - Update a gist's description by ID.
74- `duplicate_gist` - Create a copy of an existing gist with all its files.
75- `refresh_gists` - Reload your gist lists, ignoring any cached data.
76 
77### File management
78 
79- `update_gist_file` - Update the contents of a specific file in a gist.
80- `add_gist_file` - Add a new file to an existing gist.
81- `delete_gist_file` - Delete a file from a gist.
82- `rename_gist_file` - Rename an existing file within a gist.
83- `edit_gist_file` - Make targeted find-and-replace edits to a gist file.
84 
85### Comments
86 
87- `list_gist_comments` - List all comments for a specified gist.
88- `add_gist_comment` - Add a new comment to a gist.
89- `edit_gist_comment` - Update the content of an existing comment.
90- `delete_gist_comment` - Delete a comment from a gist.
91 
92## 🛠️ Optional tools
93 
94The following tool sets are disabled by default to keep the tool surface minimal. Enable them by passing the corresponding CLI flag.
95 
96#### Daily notes (`--daily`)
97 
98- `get_todays_note` - Get or create today's daily note.
99- `update_todays_note` - Update the content of today's daily note.
100- `list_daily_notes` - List all of your daily notes.
101- `get_daily_note` - Get the contents of a specific daily note by date.
102- `delete_daily_note` - Delete a specific daily note by date.
103 
104#### Starring (`--starred`)
105 
106- `list_starred_gists` - List all your starred gists.
107- `star_gist` - Star a specific gist by ID.
108- `unstar_gist` - Unstar a starred gist by ID.
109 
110#### Archiving (`--archived`)
111 
112- `list_archived_gists` - List all of your archived gists.
113- `archive_gist` - Archive one of your gists.
114- `unarchive_gist` - Unarchive an archived gist.
115 
116#### Prompts (`--prompts`)
117 
118- `list_gist_prompts` - List the prompts in your prompts collection.
119- `add_gist_prompt` - Add a new prompt to your prompts collection.
120- `delete_gist_prompt` - Delete a prompt from your collection.
121 
122## 📁 Included resources
123 
124In addition to the above tools, the GistPad MCP server also exposes your gists as resources (using the `gist:///` URI scheme), which allows clients to read them without requiring tool execution.
125 
126When you add/delete/duplicate a gist, or change a gist's description, then a notification will be provided to MCP clients, indicating that the list of resources have changed. And if your MCP client supports resource subscriptions, then you can subscribe to a specific gist and get notified when it's updated.
127 
128Additionally, for MCP clients that support resource templates, GistPad also exposes a resource at `gist:///{gistId}/comments`, which allows querying the comments for a gist (without needing to execute the `list_gist_comments` tool).
129 
130### Resource configuration
131 
132If you'd like to expose either your archived gists, starred gists, and/or daily notes as resources, then simply update your MCP server config to pass the `--archived`, `--starred`, and/or `--daily` flags to the `gistpad-mcp` CLI.
133 
134## 💬 Reusable prompts
135 
136GistPad allows you to create and manage parameterized/reusable prompts that are stored as markdown files in a gist. You can manage prompts using the `add_prompt` and `delete_prompt` tool, by simply asking your MCP client to create/delete a prompt, with the specified contents/arguments you want.
137 
138Behind the scenes, prompts are stored as markdown files in a gist called `💬 Prompts` (which is automatically created by the `add_prompt` tool). The prompt files include their prompt as the body, and optionally, a description and arguments using front-matter. And if the prompt makes use of arguments, the body of the prompt should include `{{argument}}` placeholders, which will be replaced when the MCP client retrieves it.
139 
140## 💻 CLI Reference
141 
142The `gistpad-mcp` CLI accepts the following optional flags:
143 
144- `--archived` - Enable archive tools and include archived gists in resources
145- `--starred` - Enable starring tools and include starred gists in resources
146- `--daily` - Enable daily note tools and include daily notes in resources
147- `--prompts` - Enable prompt tools and MCP prompt handlers
148- `--markdown` - Filter gists to only those composed of Markdown files
149 
150## 🧰 Troubleshooting
151 
152- <u>Not seeing a gist in your list?</u> The GistPad MCP server caches your gist list and updates it 1) anytime you make a change through the MCP server, or 2) every hour. However, if you add/edit/delete a gist using an external client, you may need to tell GistPad MCP to refresh itself (assuming it hasn't performed its hourly refresh yet). You can do this by triggering the `refresh_gists` tool (e.g. running `#refresh_gists` in VS Code Copilot chat).
153