This is page 1 of 5. Use http://codebase.md/modelcontextprotocol/servers?lines=true&page={x} to view the full context.
# Directory Structure
```
├── .gitattributes
├── .github
│ ├── pull_request_template.md
│ └── workflows
│ ├── claude.yml
│ ├── python.yml
│ ├── release.yml
│ └── typescript.yml
├── .gitignore
├── .mcp.json
├── .npmrc
├── .vscode
│ └── settings.json
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── package-lock.json
├── package.json
├── README.md
├── scripts
│ └── release.py
├── SECURITY.md
├── src
│ ├── everything
│ │ ├── CLAUDE.md
│ │ ├── Dockerfile
│ │ ├── everything.ts
│ │ ├── index.ts
│ │ ├── instructions.md
│ │ ├── package.json
│ │ ├── README.md
│ │ ├── sse.ts
│ │ ├── stdio.ts
│ │ ├── streamableHttp.ts
│ │ └── tsconfig.json
│ ├── fetch
│ │ ├── .python-version
│ │ ├── Dockerfile
│ │ ├── LICENSE
│ │ ├── pyproject.toml
│ │ ├── README.md
│ │ ├── src
│ │ │ └── mcp_server_fetch
│ │ │ ├── __init__.py
│ │ │ ├── __main__.py
│ │ │ └── server.py
│ │ └── uv.lock
│ ├── filesystem
│ │ ├── __tests__
│ │ │ ├── directory-tree.test.ts
│ │ │ ├── lib.test.ts
│ │ │ ├── path-utils.test.ts
│ │ │ ├── path-validation.test.ts
│ │ │ └── roots-utils.test.ts
│ │ ├── Dockerfile
│ │ ├── index.ts
│ │ ├── lib.ts
│ │ ├── package.json
│ │ ├── path-utils.ts
│ │ ├── path-validation.ts
│ │ ├── README.md
│ │ ├── roots-utils.ts
│ │ ├── tsconfig.json
│ │ └── vitest.config.ts
│ ├── git
│ │ ├── .gitignore
│ │ ├── .python-version
│ │ ├── Dockerfile
│ │ ├── LICENSE
│ │ ├── pyproject.toml
│ │ ├── README.md
│ │ ├── src
│ │ │ └── mcp_server_git
│ │ │ ├── __init__.py
│ │ │ ├── __main__.py
│ │ │ ├── py.typed
│ │ │ └── server.py
│ │ ├── tests
│ │ │ └── test_server.py
│ │ └── uv.lock
│ ├── memory
│ │ ├── __tests__
│ │ │ ├── file-path.test.ts
│ │ │ └── knowledge-graph.test.ts
│ │ ├── Dockerfile
│ │ ├── index.ts
│ │ ├── package.json
│ │ ├── README.md
│ │ ├── tsconfig.json
│ │ └── vitest.config.ts
│ ├── sequentialthinking
│ │ ├── __tests__
│ │ │ └── lib.test.ts
│ │ ├── Dockerfile
│ │ ├── index.ts
│ │ ├── lib.ts
│ │ ├── package.json
│ │ ├── README.md
│ │ ├── tsconfig.json
│ │ └── vitest.config.ts
│ └── time
│ ├── .python-version
│ ├── Dockerfile
│ ├── pyproject.toml
│ ├── README.md
│ ├── src
│ │ └── mcp_server_time
│ │ ├── __init__.py
│ │ ├── __main__.py
│ │ └── server.py
│ ├── test
│ │ └── time_server_test.py
│ └── uv.lock
└── tsconfig.json
```
# Files
--------------------------------------------------------------------------------
/src/fetch/.python-version:
--------------------------------------------------------------------------------
```
1 | 3.11
2 |
```
--------------------------------------------------------------------------------
/src/git/.python-version:
--------------------------------------------------------------------------------
```
1 | 3.10
2 |
```
--------------------------------------------------------------------------------
/src/time/.python-version:
--------------------------------------------------------------------------------
```
1 | 3.10
2 |
```
--------------------------------------------------------------------------------
/src/git/.gitignore:
--------------------------------------------------------------------------------
```
1 | __pycache__
2 | .venv
3 |
```
--------------------------------------------------------------------------------
/.gitattributes:
--------------------------------------------------------------------------------
```
1 | package-lock.json linguist-generated=true
2 |
```
--------------------------------------------------------------------------------
/.npmrc:
--------------------------------------------------------------------------------
```
1 | registry="https://registry.npmjs.org/"
2 | @modelcontextprotocol:registry="https://registry.npmjs.org/"
3 |
```
--------------------------------------------------------------------------------
/.mcp.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "mcpServers": {
3 | "mcp-docs": {
4 | "type": "http",
5 | "url": "https://modelcontextprotocol.io/mcp"
6 | }
7 | }
8 | }
9 |
```
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
1 | # Logs
2 | logs
3 | *.log
4 | npm-debug.log*
5 | yarn-debug.log*
6 | yarn-error.log*
7 | lerna-debug.log*
8 | .pnpm-debug.log*
9 |
10 | # Diagnostic reports (https://nodejs.org/api/report.html)
11 | report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
12 |
13 | # Runtime data
14 | pids
15 | *.pid
16 | *.seed
17 | *.pid.lock
18 |
19 | # Directory for instrumented libs generated by jscoverage/JSCover
20 | lib-cov
21 |
22 | # Coverage directory used by tools like istanbul
23 | coverage
24 | *.lcov
25 |
26 | # nyc test coverage
27 | .nyc_output
28 |
29 | # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
30 | .grunt
31 |
32 | # Bower dependency directory (https://bower.io/)
33 | bower_components
34 |
35 | # node-waf configuration
36 | .lock-wscript
37 |
38 | # Compiled binary addons (https://nodejs.org/api/addons.html)
39 | build/Release
40 |
41 | # Dependency directories
42 | node_modules/
43 | jspm_packages/
44 |
45 | # Snowpack dependency directory (https://snowpack.dev/)
46 | web_modules/
47 |
48 | # TypeScript cache
49 | *.tsbuildinfo
50 |
51 | # Optional npm cache directory
52 | .npm
53 |
54 | # Optional eslint cache
55 | .eslintcache
56 |
57 | # Optional stylelint cache
58 | .stylelintcache
59 |
60 | # Microbundle cache
61 | .rpt2_cache/
62 | .rts2_cache_cjs/
63 | .rts2_cache_es/
64 | .rts2_cache_umd/
65 |
66 | # Optional REPL history
67 | .node_repl_history
68 |
69 | # Output of 'npm pack'
70 | *.tgz
71 |
72 | # Yarn Integrity file
73 | .yarn-integrity
74 |
75 | # dotenv environment variable files
76 | .env
77 | .env.development.local
78 | .env.test.local
79 | .env.production.local
80 | .env.local
81 |
82 | # parcel-bundler cache (https://parceljs.org/)
83 | .cache
84 | .parcel-cache
85 |
86 | # Next.js build output
87 | .next
88 | out
89 |
90 | # Nuxt.js build / generate output
91 | .nuxt
92 | dist
93 |
94 | # Gatsby files
95 | .cache/
96 | # Comment in the public line in if your project uses Gatsby and not Next.js
97 | # https://nextjs.org/blog/next-9-1#public-directory-support
98 | # public
99 |
100 | # vuepress build output
101 | .vuepress/dist
102 |
103 | # vuepress v2.x temp and cache directory
104 | .temp
105 | .cache
106 |
107 | # Docusaurus cache and generated files
108 | .docusaurus
109 |
110 | # Serverless directories
111 | .serverless/
112 |
113 | # FuseBox cache
114 | .fusebox/
115 |
116 | # DynamoDB Local files
117 | .dynamodb/
118 |
119 | # TernJS port file
120 | .tern-port
121 |
122 | # Stores VSCode versions used for testing VSCode extensions
123 | .vscode-test
124 |
125 | # Jetbrains IDEs
126 | .idea/
127 |
128 | # yarn v2
129 | .yarn/cache
130 | .yarn/unplugged
131 | .yarn/build-state.yml
132 | .yarn/install-state.gz
133 | .pnp.*
134 |
135 | build/
136 |
137 | gcp-oauth.keys.json
138 | .*-server-credentials.json
139 |
140 | # Byte-compiled / optimized / DLL files
141 | __pycache__/
142 | *.py[cod]
143 | *$py.class
144 |
145 | # C extensions
146 | *.so
147 |
148 | # Distribution / packaging
149 | .Python
150 | build/
151 | develop-eggs/
152 | dist/
153 | downloads/
154 | eggs/
155 | .eggs/
156 | lib/
157 | lib64/
158 | parts/
159 | sdist/
160 | var/
161 | wheels/
162 | share/python-wheels/
163 | *.egg-info/
164 | .installed.cfg
165 | *.egg
166 | MANIFEST
167 |
168 | # PyInstaller
169 | # Usually these files are written by a python script from a template
170 | # before PyInstaller builds the exe, so as to inject date/other infos into it.
171 | *.manifest
172 | *.spec
173 |
174 | # Installer logs
175 | pip-log.txt
176 | pip-delete-this-directory.txt
177 |
178 | # Unit test / coverage reports
179 | htmlcov/
180 | .tox/
181 | .nox/
182 | .coverage
183 | .coverage.*
184 | .cache
185 | nosetests.xml
186 | coverage.xml
187 | *.cover
188 | *.py,cover
189 | .hypothesis/
190 | .pytest_cache/
191 | cover/
192 |
193 | # Translations
194 | *.mo
195 | *.pot
196 |
197 | # Django stuff:
198 | *.log
199 | local_settings.py
200 | db.sqlite3
201 | db.sqlite3-journal
202 |
203 | # Flask stuff:
204 | instance/
205 | .webassets-cache
206 |
207 | # Scrapy stuff:
208 | .scrapy
209 |
210 | # Sphinx documentation
211 | docs/_build/
212 |
213 | # PyBuilder
214 | .pybuilder/
215 | target/
216 |
217 | # Jupyter Notebook
218 | .ipynb_checkpoints
219 |
220 | # IPython
221 | profile_default/
222 | ipython_config.py
223 |
224 | # pyenv
225 | # For a library or package, you might want to ignore these files since the code is
226 | # intended to run in multiple environments; otherwise, check them in:
227 | # .python-version
228 |
229 | # pipenv
230 | # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
231 | # However, in case of collaboration, if having platform-specific dependencies or dependencies
232 | # having no cross-platform support, pipenv may install dependencies that don't work, or not
233 | # install all needed dependencies.
234 | #Pipfile.lock
235 |
236 | # poetry
237 | # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
238 | # This is especially recommended for binary packages to ensure reproducibility, and is more
239 | # commonly ignored for libraries.
240 | # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
241 | #poetry.lock
242 |
243 | # pdm
244 | # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
245 | #pdm.lock
246 | # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
247 | # in version control.
248 | # https://pdm.fming.dev/latest/usage/project/#working-with-version-control
249 | .pdm.toml
250 | .pdm-python
251 | .pdm-build/
252 |
253 | # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
254 | __pypackages__/
255 |
256 | # Celery stuff
257 | celerybeat-schedule
258 | celerybeat.pid
259 |
260 | # SageMath parsed files
261 | *.sage.py
262 |
263 | # Environments
264 | .env
265 | .venv
266 | env/
267 | venv/
268 | ENV/
269 | env.bak/
270 | venv.bak/
271 |
272 | # Spyder project settings
273 | .spyderproject
274 | .spyproject
275 |
276 | # Rope project settings
277 | .ropeproject
278 |
279 | # mkdocs documentation
280 | /site
281 |
282 | # mypy
283 | .mypy_cache/
284 | .dmypy.json
285 | dmypy.json
286 |
287 | # Pyre type checker
288 | .pyre/
289 |
290 | # pytype static type analyzer
291 | .pytype/
292 |
293 | # Cython debug symbols
294 | cython_debug/
295 |
296 | .DS_Store
297 |
298 | # PyCharm
299 | # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
300 | # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
301 | # and can be added to the global gitignore or merged into this file. For a more nuclear
302 | # option (not recommended) you can uncomment the following to ignore the entire idea folder.
303 | #.idea/
304 | .claude/settings.local.json
305 |
```
--------------------------------------------------------------------------------
/src/sequentialthinking/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Sequential Thinking MCP Server
2 |
3 | An MCP server implementation that provides a tool for dynamic and reflective problem-solving through a structured thinking process.
4 |
5 | ## Features
6 |
7 | - Break down complex problems into manageable steps
8 | - Revise and refine thoughts as understanding deepens
9 | - Branch into alternative paths of reasoning
10 | - Adjust the total number of thoughts dynamically
11 | - Generate and verify solution hypotheses
12 |
13 | ## Tool
14 |
15 | ### sequential_thinking
16 |
17 | Facilitates a detailed, step-by-step thinking process for problem-solving and analysis.
18 |
19 | **Inputs:**
20 | - `thought` (string): The current thinking step
21 | - `nextThoughtNeeded` (boolean): Whether another thought step is needed
22 | - `thoughtNumber` (integer): Current thought number
23 | - `totalThoughts` (integer): Estimated total thoughts needed
24 | - `isRevision` (boolean, optional): Whether this revises previous thinking
25 | - `revisesThought` (integer, optional): Which thought is being reconsidered
26 | - `branchFromThought` (integer, optional): Branching point thought number
27 | - `branchId` (string, optional): Branch identifier
28 | - `needsMoreThoughts` (boolean, optional): If more thoughts are needed
29 |
30 | ## Usage
31 |
32 | The Sequential Thinking tool is designed for:
33 | - Breaking down complex problems into steps
34 | - Planning and design with room for revision
35 | - Analysis that might need course correction
36 | - Problems where the full scope might not be clear initially
37 | - Tasks that need to maintain context over multiple steps
38 | - Situations where irrelevant information needs to be filtered out
39 |
40 | ## Configuration
41 |
42 | ### Usage with Claude Desktop
43 |
44 | Add this to your `claude_desktop_config.json`:
45 |
46 | #### npx
47 |
48 | ```json
49 | {
50 | "mcpServers": {
51 | "sequential-thinking": {
52 | "command": "npx",
53 | "args": [
54 | "-y",
55 | "@modelcontextprotocol/server-sequential-thinking"
56 | ]
57 | }
58 | }
59 | }
60 | ```
61 |
62 | #### docker
63 |
64 | ```json
65 | {
66 | "mcpServers": {
67 | "sequentialthinking": {
68 | "command": "docker",
69 | "args": [
70 | "run",
71 | "--rm",
72 | "-i",
73 | "mcp/sequentialthinking"
74 | ]
75 | }
76 | }
77 | }
78 | ```
79 |
80 | To disable logging of thought information set env var: `DISABLE_THOUGHT_LOGGING` to `true`.
81 | Comment
82 |
83 | ### Usage with VS Code
84 |
85 | For quick installation, click one of the installation buttons below...
86 |
87 | [](https://insiders.vscode.dev/redirect/mcp/install?name=sequentialthinking&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-sequential-thinking%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=sequentialthinking&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-sequential-thinking%22%5D%7D&quality=insiders)
88 |
89 | [](https://insiders.vscode.dev/redirect/mcp/install?name=sequentialthinking&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22--rm%22%2C%22-i%22%2C%22mcp%2Fsequentialthinking%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=sequentialthinking&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22--rm%22%2C%22-i%22%2C%22mcp%2Fsequentialthinking%22%5D%7D&quality=insiders)
90 |
91 | For manual installation, you can configure the MCP server using one of these methods:
92 |
93 | **Method 1: User Configuration (Recommended)**
94 | Add the configuration to your user-level MCP configuration file. Open the Command Palette (`Ctrl + Shift + P`) and run `MCP: Open User Configuration`. This will open your user `mcp.json` file where you can add the server configuration.
95 |
96 | **Method 2: Workspace Configuration**
97 | Alternatively, you can add the configuration to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.
98 |
99 | > For more details about MCP configuration in VS Code, see the [official VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).
100 |
101 | For NPX installation:
102 |
103 | ```json
104 | {
105 | "servers": {
106 | "sequential-thinking": {
107 | "command": "npx",
108 | "args": [
109 | "-y",
110 | "@modelcontextprotocol/server-sequential-thinking"
111 | ]
112 | }
113 | }
114 | }
115 | ```
116 |
117 | For Docker installation:
118 |
119 | ```json
120 | {
121 | "servers": {
122 | "sequential-thinking": {
123 | "command": "docker",
124 | "args": [
125 | "run",
126 | "--rm",
127 | "-i",
128 | "mcp/sequentialthinking"
129 | ]
130 | }
131 | }
132 | }
133 | ```
134 |
135 | ### Usage with Codex CLI
136 |
137 | Run the following:
138 |
139 | #### npx
140 |
141 | ```bash
142 | codex mcp add sequential-thinking npx -y @modelcontextprotocol/server-sequential-thinking
143 | ```
144 |
145 | ## Building
146 |
147 | Docker:
148 |
149 | ```bash
150 | docker build -t mcp/sequentialthinking -f src/sequentialthinking/Dockerfile .
151 | ```
152 |
153 | ## License
154 |
155 | This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
156 |
```
--------------------------------------------------------------------------------
/src/time/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Time MCP Server
2 |
3 | <!-- mcp-name: io.github.modelcontextprotocol/server-time -->
4 |
5 | A Model Context Protocol server that provides time and timezone conversion capabilities. This server enables LLMs to get current time information and perform timezone conversions using IANA timezone names, with automatic system timezone detection.
6 |
7 | ### Available Tools
8 |
9 | - `get_current_time` - Get current time in a specific timezone or system timezone.
10 | - Required arguments:
11 | - `timezone` (string): IANA timezone name (e.g., 'America/New_York', 'Europe/London')
12 |
13 | - `convert_time` - Convert time between timezones.
14 | - Required arguments:
15 | - `source_timezone` (string): Source IANA timezone name
16 | - `time` (string): Time in 24-hour format (HH:MM)
17 | - `target_timezone` (string): Target IANA timezone name
18 |
19 | ## Installation
20 |
21 | ### Using uv (recommended)
22 |
23 | When using [`uv`](https://docs.astral.sh/uv/) no specific installation is needed. We will
24 | use [`uvx`](https://docs.astral.sh/uv/guides/tools/) to directly run *mcp-server-time*.
25 |
26 | ### Using PIP
27 |
28 | Alternatively you can install `mcp-server-time` via pip:
29 |
30 | ```bash
31 | pip install mcp-server-time
32 | ```
33 |
34 | After installation, you can run it as a script using:
35 |
36 | ```bash
37 | python -m mcp_server_time
38 | ```
39 |
40 | ## Configuration
41 |
42 | ### Configure for Claude.app
43 |
44 | Add to your Claude settings:
45 |
46 | <details>
47 | <summary>Using uvx</summary>
48 |
49 | ```json
50 | {
51 | "mcpServers": {
52 | "time": {
53 | "command": "uvx",
54 | "args": ["mcp-server-time"]
55 | }
56 | }
57 | }
58 | ```
59 | </details>
60 |
61 | <details>
62 | <summary>Using docker</summary>
63 |
64 | ```json
65 | {
66 | "mcpServers": {
67 | "time": {
68 | "command": "docker",
69 | "args": ["run", "-i", "--rm", "-e", "LOCAL_TIMEZONE", "mcp/time"]
70 | }
71 | }
72 | }
73 | ```
74 | </details>
75 |
76 | <details>
77 | <summary>Using pip installation</summary>
78 |
79 | ```json
80 | {
81 | "mcpServers": {
82 | "time": {
83 | "command": "python",
84 | "args": ["-m", "mcp_server_time"]
85 | }
86 | }
87 | }
88 | ```
89 | </details>
90 |
91 | ### Configure for Zed
92 |
93 | Add to your Zed settings.json:
94 |
95 | <details>
96 | <summary>Using uvx</summary>
97 |
98 | ```json
99 | "context_servers": [
100 | "mcp-server-time": {
101 | "command": "uvx",
102 | "args": ["mcp-server-time"]
103 | }
104 | ],
105 | ```
106 | </details>
107 |
108 | <details>
109 | <summary>Using pip installation</summary>
110 |
111 | ```json
112 | "context_servers": {
113 | "mcp-server-time": {
114 | "command": "python",
115 | "args": ["-m", "mcp_server_time"]
116 | }
117 | },
118 | ```
119 | </details>
120 |
121 | ### Configure for VS Code
122 |
123 | For quick installation, use one of the one-click install buttons below...
124 |
125 | [](https://insiders.vscode.dev/redirect/mcp/install?name=time&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-time%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=time&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-time%22%5D%7D&quality=insiders)
126 |
127 | [](https://insiders.vscode.dev/redirect/mcp/install?name=time&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22mcp%2Ftime%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=time&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22mcp%2Ftime%22%5D%7D&quality=insiders)
128 |
129 | For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`.
130 |
131 | Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.
132 |
133 | > Note that the `mcp` key is needed when using the `mcp.json` file.
134 |
135 | <details>
136 | <summary>Using uvx</summary>
137 |
138 | ```json
139 | {
140 | "mcp": {
141 | "servers": {
142 | "time": {
143 | "command": "uvx",
144 | "args": ["mcp-server-time"]
145 | }
146 | }
147 | }
148 | }
149 | ```
150 | </details>
151 |
152 | <details>
153 | <summary>Using Docker</summary>
154 |
155 | ```json
156 | {
157 | "mcp": {
158 | "servers": {
159 | "time": {
160 | "command": "docker",
161 | "args": ["run", "-i", "--rm", "mcp/time"]
162 | }
163 | }
164 | }
165 | }
166 | ```
167 | </details>
168 |
169 | ### Configure for Zencoder
170 |
171 | 1. Go to the Zencoder menu (...)
172 | 2. From the dropdown menu, select `Agent Tools`
173 | 3. Click on the `Add Custom MCP`
174 | 4. Add the name and server configuration from below, and make sure to hit the `Install` button
175 |
176 | <details>
177 | <summary>Using uvx</summary>
178 |
179 | ```json
180 | {
181 | "command": "uvx",
182 | "args": ["mcp-server-time"]
183 | }
184 | ```
185 | </details>
186 |
187 | ### Customization - System Timezone
188 |
189 | By default, the server automatically detects your system's timezone. You can override this by adding the argument `--local-timezone` to the `args` list in the configuration.
190 |
191 | Example:
192 | ```json
193 | {
194 | "command": "python",
195 | "args": ["-m", "mcp_server_time", "--local-timezone=America/New_York"]
196 | }
197 | ```
198 |
199 | ## Example Interactions
200 |
201 | 1. Get current time:
202 | ```json
203 | {
204 | "name": "get_current_time",
205 | "arguments": {
206 | "timezone": "Europe/Warsaw"
207 | }
208 | }
209 | ```
210 | Response:
211 | ```json
212 | {
213 | "timezone": "Europe/Warsaw",
214 | "datetime": "2024-01-01T13:00:00+01:00",
215 | "is_dst": false
216 | }
217 | ```
218 |
219 | 2. Convert time between timezones:
220 | ```json
221 | {
222 | "name": "convert_time",
223 | "arguments": {
224 | "source_timezone": "America/New_York",
225 | "time": "16:30",
226 | "target_timezone": "Asia/Tokyo"
227 | }
228 | }
229 | ```
230 | Response:
231 | ```json
232 | {
233 | "source": {
234 | "timezone": "America/New_York",
235 | "datetime": "2024-01-01T12:30:00-05:00",
236 | "is_dst": false
237 | },
238 | "target": {
239 | "timezone": "Asia/Tokyo",
240 | "datetime": "2024-01-01T12:30:00+09:00",
241 | "is_dst": false
242 | },
243 | "time_difference": "+13.0h",
244 | }
245 | ```
246 |
247 | ## Debugging
248 |
249 | You can use the MCP inspector to debug the server. For uvx installations:
250 |
251 | ```bash
252 | npx @modelcontextprotocol/inspector uvx mcp-server-time
253 | ```
254 |
255 | Or if you've installed the package in a specific directory or are developing on it:
256 |
257 | ```bash
258 | cd path/to/servers/src/time
259 | npx @modelcontextprotocol/inspector uv run mcp-server-time
260 | ```
261 |
262 | ## Examples of Questions for Claude
263 |
264 | 1. "What time is it now?" (will use system timezone)
265 | 2. "What time is it in Tokyo?"
266 | 3. "When it's 4 PM in New York, what time is it in London?"
267 | 4. "Convert 9:30 AM Tokyo time to New York time"
268 |
269 | ## Build
270 |
271 | Docker build:
272 |
273 | ```bash
274 | cd src/time
275 | docker build -t mcp/time .
276 | ```
277 |
278 | ## Contributing
279 |
280 | We encourage contributions to help expand and improve mcp-server-time. Whether you want to add new time-related tools, enhance existing functionality, or improve documentation, your input is valuable.
281 |
282 | For examples of other MCP servers and implementation patterns, see:
283 | https://github.com/modelcontextprotocol/servers
284 |
285 | Pull requests are welcome! Feel free to contribute new ideas, bug fixes, or enhancements to make mcp-server-time even more powerful and useful.
286 |
287 | ## License
288 |
289 | mcp-server-time is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
290 |
```
--------------------------------------------------------------------------------
/src/fetch/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Fetch MCP Server
2 |
3 | <!-- mcp-name: io.github.modelcontextprotocol/server-fetch -->
4 |
5 | A Model Context Protocol server that provides web content fetching capabilities. This server enables LLMs to retrieve and process content from web pages, converting HTML to markdown for easier consumption.
6 |
7 | > [!CAUTION]
8 | > This server can access local/internal IP addresses and may represent a security risk. Exercise caution when using this MCP server to ensure this does not expose any sensitive data.
9 |
10 | The fetch tool will truncate the response, but by using the `start_index` argument, you can specify where to start the content extraction. This lets models read a webpage in chunks, until they find the information they need.
11 |
12 | ### Available Tools
13 |
14 | - `fetch` - Fetches a URL from the internet and extracts its contents as markdown.
15 | - `url` (string, required): URL to fetch
16 | - `max_length` (integer, optional): Maximum number of characters to return (default: 5000)
17 | - `start_index` (integer, optional): Start content from this character index (default: 0)
18 | - `raw` (boolean, optional): Get raw content without markdown conversion (default: false)
19 |
20 | ### Prompts
21 |
22 | - **fetch**
23 | - Fetch a URL and extract its contents as markdown
24 | - Arguments:
25 | - `url` (string, required): URL to fetch
26 |
27 | ## Installation
28 |
29 | Optionally: Install node.js, this will cause the fetch server to use a different HTML simplifier that is more robust.
30 |
31 | ### Using uv (recommended)
32 |
33 | When using [`uv`](https://docs.astral.sh/uv/) no specific installation is needed. We will
34 | use [`uvx`](https://docs.astral.sh/uv/guides/tools/) to directly run *mcp-server-fetch*.
35 |
36 | ### Using PIP
37 |
38 | Alternatively you can install `mcp-server-fetch` via pip:
39 |
40 | ```
41 | pip install mcp-server-fetch
42 | ```
43 |
44 | After installation, you can run it as a script using:
45 |
46 | ```
47 | python -m mcp_server_fetch
48 | ```
49 |
50 | ## Configuration
51 |
52 | ### Configure for Claude.app
53 |
54 | Add to your Claude settings:
55 |
56 | <details>
57 | <summary>Using uvx</summary>
58 |
59 | ```json
60 | {
61 | "mcpServers": {
62 | "fetch": {
63 | "command": "uvx",
64 | "args": ["mcp-server-fetch"]
65 | }
66 | }
67 | }
68 | ```
69 | </details>
70 |
71 | <details>
72 | <summary>Using docker</summary>
73 |
74 | ```json
75 | {
76 | "mcpServers": {
77 | "fetch": {
78 | "command": "docker",
79 | "args": ["run", "-i", "--rm", "mcp/fetch"]
80 | }
81 | }
82 | }
83 | ```
84 | </details>
85 |
86 | <details>
87 | <summary>Using pip installation</summary>
88 |
89 | ```json
90 | {
91 | "mcpServers": {
92 | "fetch": {
93 | "command": "python",
94 | "args": ["-m", "mcp_server_fetch"]
95 | }
96 | }
97 | }
98 | ```
99 | </details>
100 |
101 | ### Configure for VS Code
102 |
103 | For quick installation, use one of the one-click install buttons below...
104 |
105 | [](https://insiders.vscode.dev/redirect/mcp/install?name=fetch&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-fetch%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=fetch&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-fetch%22%5D%7D&quality=insiders)
106 |
107 | [](https://insiders.vscode.dev/redirect/mcp/install?name=fetch&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22mcp%2Ffetch%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=fetch&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22mcp%2Ffetch%22%5D%7D&quality=insiders)
108 |
109 | For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`.
110 |
111 | Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.
112 |
113 | > Note that the `mcp` key is needed when using the `mcp.json` file.
114 |
115 | <details>
116 | <summary>Using uvx</summary>
117 |
118 | ```json
119 | {
120 | "mcp": {
121 | "servers": {
122 | "fetch": {
123 | "command": "uvx",
124 | "args": ["mcp-server-fetch"]
125 | }
126 | }
127 | }
128 | }
129 | ```
130 | </details>
131 |
132 | <details>
133 | <summary>Using Docker</summary>
134 |
135 | ```json
136 | {
137 | "mcp": {
138 | "servers": {
139 | "fetch": {
140 | "command": "docker",
141 | "args": ["run", "-i", "--rm", "mcp/fetch"]
142 | }
143 | }
144 | }
145 | }
146 | ```
147 | </details>
148 |
149 | ### Customization - robots.txt
150 |
151 | By default, the server will obey a websites robots.txt file if the request came from the model (via a tool), but not if
152 | the request was user initiated (via a prompt). This can be disabled by adding the argument `--ignore-robots-txt` to the
153 | `args` list in the configuration.
154 |
155 | ### Customization - User-agent
156 |
157 | By default, depending on if the request came from the model (via a tool), or was user initiated (via a prompt), the
158 | server will use either the user-agent
159 | ```
160 | ModelContextProtocol/1.0 (Autonomous; +https://github.com/modelcontextprotocol/servers)
161 | ```
162 | or
163 | ```
164 | ModelContextProtocol/1.0 (User-Specified; +https://github.com/modelcontextprotocol/servers)
165 | ```
166 |
167 | This can be customized by adding the argument `--user-agent=YourUserAgent` to the `args` list in the configuration.
168 |
169 | ### Customization - Proxy
170 |
171 | The server can be configured to use a proxy by using the `--proxy-url` argument.
172 |
173 | ## Windows Configuration
174 |
175 | If you're experiencing timeout issues on Windows, you may need to set the `PYTHONIOENCODING` environment variable to ensure proper character encoding:
176 |
177 | <details>
178 | <summary>Windows configuration (uvx)</summary>
179 |
180 | ```json
181 | {
182 | "mcpServers": {
183 | "fetch": {
184 | "command": "uvx",
185 | "args": ["mcp-server-fetch"],
186 | "env": {
187 | "PYTHONIOENCODING": "utf-8"
188 | }
189 | }
190 | }
191 | }
192 | ```
193 | </details>
194 |
195 | <details>
196 | <summary>Windows configuration (pip)</summary>
197 |
198 | ```json
199 | {
200 | "mcpServers": {
201 | "fetch": {
202 | "command": "python",
203 | "args": ["-m", "mcp_server_fetch"],
204 | "env": {
205 | "PYTHONIOENCODING": "utf-8"
206 | }
207 | }
208 | }
209 | }
210 | ```
211 | </details>
212 |
213 | This addresses character encoding issues that can cause the server to timeout on Windows systems.
214 |
215 | ## Debugging
216 |
217 | You can use the MCP inspector to debug the server. For uvx installations:
218 |
219 | ```
220 | npx @modelcontextprotocol/inspector uvx mcp-server-fetch
221 | ```
222 |
223 | Or if you've installed the package in a specific directory or are developing on it:
224 |
225 | ```
226 | cd path/to/servers/src/fetch
227 | npx @modelcontextprotocol/inspector uv run mcp-server-fetch
228 | ```
229 |
230 | ## Contributing
231 |
232 | We encourage contributions to help expand and improve mcp-server-fetch. Whether you want to add new tools, enhance existing functionality, or improve documentation, your input is valuable.
233 |
234 | For examples of other MCP servers and implementation patterns, see:
235 | https://github.com/modelcontextprotocol/servers
236 |
237 | Pull requests are welcome! Feel free to contribute new ideas, bug fixes, or enhancements to make mcp-server-fetch even more powerful and useful.
238 |
239 | ## License
240 |
241 | mcp-server-fetch is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
242 |
```
--------------------------------------------------------------------------------
/src/memory/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Knowledge Graph Memory Server
2 |
3 | A basic implementation of persistent memory using a local knowledge graph. This lets Claude remember information about the user across chats.
4 |
5 | ## Core Concepts
6 |
7 | ### Entities
8 | Entities are the primary nodes in the knowledge graph. Each entity has:
9 | - A unique name (identifier)
10 | - An entity type (e.g., "person", "organization", "event")
11 | - A list of observations
12 |
13 | Example:
14 | ```json
15 | {
16 | "name": "John_Smith",
17 | "entityType": "person",
18 | "observations": ["Speaks fluent Spanish"]
19 | }
20 | ```
21 |
22 | ### Relations
23 | Relations define directed connections between entities. They are always stored in active voice and describe how entities interact or relate to each other.
24 |
25 | Example:
26 | ```json
27 | {
28 | "from": "John_Smith",
29 | "to": "Anthropic",
30 | "relationType": "works_at"
31 | }
32 | ```
33 | ### Observations
34 | Observations are discrete pieces of information about an entity. They are:
35 |
36 | - Stored as strings
37 | - Attached to specific entities
38 | - Can be added or removed independently
39 | - Should be atomic (one fact per observation)
40 |
41 | Example:
42 | ```json
43 | {
44 | "entityName": "John_Smith",
45 | "observations": [
46 | "Speaks fluent Spanish",
47 | "Graduated in 2019",
48 | "Prefers morning meetings"
49 | ]
50 | }
51 | ```
52 |
53 | ## API
54 |
55 | ### Tools
56 | - **create_entities**
57 | - Create multiple new entities in the knowledge graph
58 | - Input: `entities` (array of objects)
59 | - Each object contains:
60 | - `name` (string): Entity identifier
61 | - `entityType` (string): Type classification
62 | - `observations` (string[]): Associated observations
63 | - Ignores entities with existing names
64 |
65 | - **create_relations**
66 | - Create multiple new relations between entities
67 | - Input: `relations` (array of objects)
68 | - Each object contains:
69 | - `from` (string): Source entity name
70 | - `to` (string): Target entity name
71 | - `relationType` (string): Relationship type in active voice
72 | - Skips duplicate relations
73 |
74 | - **add_observations**
75 | - Add new observations to existing entities
76 | - Input: `observations` (array of objects)
77 | - Each object contains:
78 | - `entityName` (string): Target entity
79 | - `contents` (string[]): New observations to add
80 | - Returns added observations per entity
81 | - Fails if entity doesn't exist
82 |
83 | - **delete_entities**
84 | - Remove entities and their relations
85 | - Input: `entityNames` (string[])
86 | - Cascading deletion of associated relations
87 | - Silent operation if entity doesn't exist
88 |
89 | - **delete_observations**
90 | - Remove specific observations from entities
91 | - Input: `deletions` (array of objects)
92 | - Each object contains:
93 | - `entityName` (string): Target entity
94 | - `observations` (string[]): Observations to remove
95 | - Silent operation if observation doesn't exist
96 |
97 | - **delete_relations**
98 | - Remove specific relations from the graph
99 | - Input: `relations` (array of objects)
100 | - Each object contains:
101 | - `from` (string): Source entity name
102 | - `to` (string): Target entity name
103 | - `relationType` (string): Relationship type
104 | - Silent operation if relation doesn't exist
105 |
106 | - **read_graph**
107 | - Read the entire knowledge graph
108 | - No input required
109 | - Returns complete graph structure with all entities and relations
110 |
111 | - **search_nodes**
112 | - Search for nodes based on query
113 | - Input: `query` (string)
114 | - Searches across:
115 | - Entity names
116 | - Entity types
117 | - Observation content
118 | - Returns matching entities and their relations
119 |
120 | - **open_nodes**
121 | - Retrieve specific nodes by name
122 | - Input: `names` (string[])
123 | - Returns:
124 | - Requested entities
125 | - Relations between requested entities
126 | - Silently skips non-existent nodes
127 |
128 | # Usage with Claude Desktop
129 |
130 | ### Setup
131 |
132 | Add this to your claude_desktop_config.json:
133 |
134 | #### Docker
135 |
136 | ```json
137 | {
138 | "mcpServers": {
139 | "memory": {
140 | "command": "docker",
141 | "args": ["run", "-i", "-v", "claude-memory:/app/dist", "--rm", "mcp/memory"]
142 | }
143 | }
144 | }
145 | ```
146 |
147 | #### NPX
148 | ```json
149 | {
150 | "mcpServers": {
151 | "memory": {
152 | "command": "npx",
153 | "args": [
154 | "-y",
155 | "@modelcontextprotocol/server-memory"
156 | ]
157 | }
158 | }
159 | }
160 | ```
161 |
162 | #### NPX with custom setting
163 |
164 | The server can be configured using the following environment variables:
165 |
166 | ```json
167 | {
168 | "mcpServers": {
169 | "memory": {
170 | "command": "npx",
171 | "args": [
172 | "-y",
173 | "@modelcontextprotocol/server-memory"
174 | ],
175 | "env": {
176 | "MEMORY_FILE_PATH": "/path/to/custom/memory.jsonl"
177 | }
178 | }
179 | }
180 | }
181 | ```
182 |
183 | - `MEMORY_FILE_PATH`: Path to the memory storage JSONL file (default: `memory.jsonl` in the server directory)
184 |
185 | # VS Code Installation Instructions
186 |
187 | For quick installation, use one of the one-click installation buttons below:
188 |
189 | [](https://insiders.vscode.dev/redirect/mcp/install?name=memory&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-memory%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=memory&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-memory%22%5D%7D&quality=insiders)
190 |
191 | [](https://insiders.vscode.dev/redirect/mcp/install?name=memory&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22-v%22%2C%22claude-memory%3A%2Fapp%2Fdist%22%2C%22--rm%22%2C%22mcp%2Fmemory%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=memory&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22-v%22%2C%22claude-memory%3A%2Fapp%2Fdist%22%2C%22--rm%22%2C%22mcp%2Fmemory%22%5D%7D&quality=insiders)
192 |
193 | For manual installation, you can configure the MCP server using one of these methods:
194 |
195 | **Method 1: User Configuration (Recommended)**
196 | Add the configuration to your user-level MCP configuration file. Open the Command Palette (`Ctrl + Shift + P`) and run `MCP: Open User Configuration`. This will open your user `mcp.json` file where you can add the server configuration.
197 |
198 | **Method 2: Workspace Configuration**
199 | Alternatively, you can add the configuration to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.
200 |
201 | > For more details about MCP configuration in VS Code, see the [official VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).
202 |
203 | #### NPX
204 |
205 | ```json
206 | {
207 | "servers": {
208 | "memory": {
209 | "command": "npx",
210 | "args": [
211 | "-y",
212 | "@modelcontextprotocol/server-memory"
213 | ]
214 | }
215 | }
216 | }
217 | ```
218 |
219 | #### Docker
220 |
221 | ```json
222 | {
223 | "servers": {
224 | "memory": {
225 | "command": "docker",
226 | "args": [
227 | "run",
228 | "-i",
229 | "-v",
230 | "claude-memory:/app/dist",
231 | "--rm",
232 | "mcp/memory"
233 | ]
234 | }
235 | }
236 | }
237 | ```
238 |
239 | ### System Prompt
240 |
241 | The prompt for utilizing memory depends on the use case. Changing the prompt will help the model determine the frequency and types of memories created.
242 |
243 | Here is an example prompt for chat personalization. You could use this prompt in the "Custom Instructions" field of a [Claude.ai Project](https://www.anthropic.com/news/projects).
244 |
245 | ```
246 | Follow these steps for each interaction:
247 |
248 | 1. User Identification:
249 | - You should assume that you are interacting with default_user
250 | - If you have not identified default_user, proactively try to do so.
251 |
252 | 2. Memory Retrieval:
253 | - Always begin your chat by saying only "Remembering..." and retrieve all relevant information from your knowledge graph
254 | - Always refer to your knowledge graph as your "memory"
255 |
256 | 3. Memory
257 | - While conversing with the user, be attentive to any new information that falls into these categories:
258 | a) Basic Identity (age, gender, location, job title, education level, etc.)
259 | b) Behaviors (interests, habits, etc.)
260 | c) Preferences (communication style, preferred language, etc.)
261 | d) Goals (goals, targets, aspirations, etc.)
262 | e) Relationships (personal and professional relationships up to 3 degrees of separation)
263 |
264 | 4. Memory Update:
265 | - If any new information was gathered during the interaction, update your memory as follows:
266 | a) Create entities for recurring organizations, people, and significant events
267 | b) Connect them to the current entities using relations
268 | c) Store facts about them as observations
269 | ```
270 |
271 | ## Building
272 |
273 | Docker:
274 |
275 | ```sh
276 | docker build -t mcp/memory -f src/memory/Dockerfile .
277 | ```
278 |
279 | For Awareness: a prior mcp/memory volume contains an index.js file that could be overwritten by the new container. If you are using a docker volume for storage, delete the old docker volume's `index.js` file before starting the new container.
280 |
281 | ## License
282 |
283 | This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
284 |
```
--------------------------------------------------------------------------------
/src/everything/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Everything MCP Server
2 |
3 | This MCP server attempts to exercise all the features of the MCP protocol. It is not intended to be a useful server, but rather a test server for builders of MCP clients. It implements prompts, tools, resources, sampling, and more to showcase MCP capabilities.
4 |
5 | ## Components
6 |
7 | ### Tools
8 |
9 | 1. `echo`
10 | - Simple tool to echo back input messages
11 | - Input:
12 | - `message` (string): Message to echo back
13 | - Returns: Text content with echoed message
14 |
15 | 2. `add`
16 | - Adds two numbers together
17 | - Inputs:
18 | - `a` (number): First number
19 | - `b` (number): Second number
20 | - Returns: Text result of the addition
21 |
22 | 3. `longRunningOperation`
23 | - Demonstrates progress notifications for long operations
24 | - Inputs:
25 | - `duration` (number, default: 10): Duration in seconds
26 | - `steps` (number, default: 5): Number of progress steps
27 | - Returns: Completion message with duration and steps
28 | - Sends progress notifications during execution
29 |
30 | 4. `printEnv`
31 | - Prints all environment variables
32 | - Useful for debugging MCP server configuration
33 | - No inputs required
34 | - Returns: JSON string of all environment variables
35 |
36 | 5. `sampleLLM`
37 | - Demonstrates LLM sampling capability using MCP sampling feature
38 | - Inputs:
39 | - `prompt` (string): The prompt to send to the LLM
40 | - `maxTokens` (number, default: 100): Maximum tokens to generate
41 | - Returns: Generated LLM response
42 |
43 | 6. `getTinyImage`
44 | - Returns a small test image
45 | - No inputs required
46 | - Returns: Base64 encoded PNG image data
47 |
48 | 7. `annotatedMessage`
49 | - Demonstrates how annotations can be used to provide metadata about content
50 | - Inputs:
51 | - `messageType` (enum: "error" | "success" | "debug"): Type of message to demonstrate different annotation patterns
52 | - `includeImage` (boolean, default: false): Whether to include an example image
53 | - Returns: Content with varying annotations:
54 | - Error messages: High priority (1.0), visible to both user and assistant
55 | - Success messages: Medium priority (0.7), user-focused
56 | - Debug messages: Low priority (0.3), assistant-focused
57 | - Optional image: Medium priority (0.5), user-focused
58 | - Example annotations:
59 | ```json
60 | {
61 | "priority": 1.0,
62 | "audience": ["user", "assistant"]
63 | }
64 | ```
65 |
66 | 8. `getResourceReference`
67 | - Returns a resource reference that can be used by MCP clients
68 | - Inputs:
69 | - `resourceId` (number, 1-100): ID of the resource to reference
70 | - Returns: A resource reference with:
71 | - Text introduction
72 | - Embedded resource with `type: "resource"`
73 | - Text instruction for using the resource URI
74 |
75 | 9. `startElicitation`
76 | - Initiates an elicitation (interaction) within the MCP client.
77 | - Inputs:
78 | - `color` (string): Favorite color
79 | - `number` (number, 1-100): Favorite number
80 | - `pets` (enum): Favorite pet
81 | - Returns: Confirmation of the elicitation demo with selection summary.
82 |
83 | 10. `structuredContent`
84 | - Demonstrates a tool returning structured content using the example in the specification
85 | - Provides an output schema to allow testing of client SHOULD advisory to validate the result using the schema
86 | - Inputs:
87 | - `location` (string): A location or ZIP code, mock data is returned regardless of value
88 | - Returns: a response with
89 | - `structuredContent` field conformant to the output schema
90 | - A backward compatible Text Content field, a SHOULD advisory in the specification
91 |
92 | 11. `listRoots`
93 | - Lists the current MCP roots provided by the client
94 | - Demonstrates the roots protocol capability even though this server doesn't access files
95 | - No inputs required
96 | - Returns: List of current roots with their URIs and names, or a message if no roots are set
97 | - Shows how servers can interact with the MCP roots protocol
98 |
99 | ### Resources
100 |
101 | The server provides 100 test resources in two formats:
102 | - Even numbered resources:
103 | - Plaintext format
104 | - URI pattern: `test://static/resource/{even_number}`
105 | - Content: Simple text description
106 |
107 | - Odd numbered resources:
108 | - Binary blob format
109 | - URI pattern: `test://static/resource/{odd_number}`
110 | - Content: Base64 encoded binary data
111 |
112 | Resource features:
113 | - Supports pagination (10 items per page)
114 | - Allows subscribing to resource updates
115 | - Demonstrates resource templates
116 | - Auto-updates subscribed resources every 5 seconds
117 |
118 | ### Prompts
119 |
120 | 1. `simple_prompt`
121 | - Basic prompt without arguments
122 | - Returns: Single message exchange
123 |
124 | 2. `complex_prompt`
125 | - Advanced prompt demonstrating argument handling
126 | - Required arguments:
127 | - `temperature` (string): Temperature setting
128 | - Optional arguments:
129 | - `style` (string): Output style preference
130 | - Returns: Multi-turn conversation with images
131 |
132 | 3. `resource_prompt`
133 | - Demonstrates embedding resource references in prompts
134 | - Required arguments:
135 | - `resourceId` (number): ID of the resource to embed (1-100)
136 | - Returns: Multi-turn conversation with an embedded resource reference
137 | - Shows how to include resources directly in prompt messages
138 |
139 | ### Roots
140 |
141 | The server demonstrates the MCP roots protocol capability:
142 |
143 | - Declares `roots: { listChanged: true }` capability to indicate support for roots
144 | - Handles `roots/list_changed` notifications from clients
145 | - Requests initial roots during server initialization
146 | - Provides a `listRoots` tool to display current roots
147 | - Logs roots-related events for demonstration purposes
148 |
149 | Note: This server doesn't actually access files, but demonstrates how servers can interact with the roots protocol for clients that need to understand which directories are available for file operations.
150 |
151 | ### Logging
152 |
153 | The server sends random-leveled log messages every 15 seconds, e.g.:
154 |
155 | ```json
156 | {
157 | "method": "notifications/message",
158 | "params": {
159 | "level": "info",
160 | "data": "Info-level message"
161 | }
162 | }
163 | ```
164 |
165 | ## Usage with Claude Desktop (uses [stdio Transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#stdio))
166 |
167 | Add to your `claude_desktop_config.json`:
168 |
169 | ```json
170 | {
171 | "mcpServers": {
172 | "everything": {
173 | "command": "npx",
174 | "args": [
175 | "-y",
176 | "@modelcontextprotocol/server-everything"
177 | ]
178 | }
179 | }
180 | }
181 | ```
182 |
183 | ## Usage with VS Code
184 |
185 | For quick installation, use of of the one-click install buttons below...
186 |
187 | [](https://insiders.vscode.dev/redirect/mcp/install?name=everything&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-everything%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=everything&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-everything%22%5D%7D&quality=insiders)
188 |
189 | [](https://insiders.vscode.dev/redirect/mcp/install?name=everything&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22mcp%2Feverything%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=everything&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22mcp%2Feverything%22%5D%7D&quality=insiders)
190 |
191 | For manual installation, you can configure the MCP server using one of these methods:
192 |
193 | **Method 1: User Configuration (Recommended)**
194 | Add the configuration to your user-level MCP configuration file. Open the Command Palette (`Ctrl + Shift + P`) and run `MCP: Open User Configuration`. This will open your user `mcp.json` file where you can add the server configuration.
195 |
196 | **Method 2: Workspace Configuration**
197 | Alternatively, you can add the configuration to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.
198 |
199 | > For more details about MCP configuration in VS Code, see the [official VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).
200 |
201 | #### NPX
202 |
203 | ```json
204 | {
205 | "servers": {
206 | "everything": {
207 | "command": "npx",
208 | "args": ["-y", "@modelcontextprotocol/server-everything"]
209 | }
210 | }
211 | }
212 | ```
213 |
214 | ## Running from source with [HTTP+SSE Transport](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse) (deprecated as of [2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports))
215 |
216 | ```shell
217 | cd src/everything
218 | npm install
219 | npm run start:sse
220 | ```
221 |
222 | ## Run from source with [Streamable HTTP Transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http)
223 |
224 | ```shell
225 | cd src/everything
226 | npm install
227 | npm run start:streamableHttp
228 | ```
229 |
230 | ## Running as an installed package
231 | ### Install
232 | ```shell
233 | npm install -g @modelcontextprotocol/server-everything@latest
234 | ````
235 |
236 | ### Run the default (stdio) server
237 | ```shell
238 | npx @modelcontextprotocol/server-everything
239 | ```
240 |
241 | ### Or specify stdio explicitly
242 | ```shell
243 | npx @modelcontextprotocol/server-everything stdio
244 | ```
245 |
246 | ### Run the SSE server
247 | ```shell
248 | npx @modelcontextprotocol/server-everything sse
249 | ```
250 |
251 | ### Run the streamable HTTP server
252 | ```shell
253 | npx @modelcontextprotocol/server-everything streamableHttp
254 | ```
255 |
256 |
```
--------------------------------------------------------------------------------
/src/git/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # mcp-server-git: A git MCP server
2 |
3 | <!-- mcp-name: io.github.modelcontextprotocol/server-git -->
4 |
5 | ## Overview
6 |
7 | A Model Context Protocol server for Git repository interaction and automation. This server provides tools to read, search, and manipulate Git repositories via Large Language Models.
8 |
9 | Please note that mcp-server-git is currently in early development. The functionality and available tools are subject to change and expansion as we continue to develop and improve the server.
10 |
11 | ### Tools
12 |
13 | 1. `git_status`
14 | - Shows the working tree status
15 | - Input:
16 | - `repo_path` (string): Path to Git repository
17 | - Returns: Current status of working directory as text output
18 |
19 | 2. `git_diff_unstaged`
20 | - Shows changes in working directory not yet staged
21 | - Inputs:
22 | - `repo_path` (string): Path to Git repository
23 | - `context_lines` (number, optional): Number of context lines to show (default: 3)
24 | - Returns: Diff output of unstaged changes
25 |
26 | 3. `git_diff_staged`
27 | - Shows changes that are staged for commit
28 | - Inputs:
29 | - `repo_path` (string): Path to Git repository
30 | - `context_lines` (number, optional): Number of context lines to show (default: 3)
31 | - Returns: Diff output of staged changes
32 |
33 | 4. `git_diff`
34 | - Shows differences between branches or commits
35 | - Inputs:
36 | - `repo_path` (string): Path to Git repository
37 | - `target` (string): Target branch or commit to compare with
38 | - `context_lines` (number, optional): Number of context lines to show (default: 3)
39 | - Returns: Diff output comparing current state with target
40 |
41 | 5. `git_commit`
42 | - Records changes to the repository
43 | - Inputs:
44 | - `repo_path` (string): Path to Git repository
45 | - `message` (string): Commit message
46 | - Returns: Confirmation with new commit hash
47 |
48 | 6. `git_add`
49 | - Adds file contents to the staging area
50 | - Inputs:
51 | - `repo_path` (string): Path to Git repository
52 | - `files` (string[]): Array of file paths to stage
53 | - Returns: Confirmation of staged files
54 |
55 | 7. `git_reset`
56 | - Unstages all staged changes
57 | - Input:
58 | - `repo_path` (string): Path to Git repository
59 | - Returns: Confirmation of reset operation
60 |
61 | 8. `git_log`
62 | - Shows the commit logs with optional date filtering
63 | - Inputs:
64 | - `repo_path` (string): Path to Git repository
65 | - `max_count` (number, optional): Maximum number of commits to show (default: 10)
66 | - `start_timestamp` (string, optional): Start timestamp for filtering commits. Accepts ISO 8601 format (e.g., '2024-01-15T14:30:25'), relative dates (e.g., '2 weeks ago', 'yesterday'), or absolute dates (e.g., '2024-01-15', 'Jan 15 2024')
67 | - `end_timestamp` (string, optional): End timestamp for filtering commits. Accepts ISO 8601 format (e.g., '2024-01-15T14:30:25'), relative dates (e.g., '2 weeks ago', 'yesterday'), or absolute dates (e.g., '2024-01-15', 'Jan 15 2024')
68 | - Returns: Array of commit entries with hash, author, date, and message
69 |
70 | 9. `git_create_branch`
71 | - Creates a new branch
72 | - Inputs:
73 | - `repo_path` (string): Path to Git repository
74 | - `branch_name` (string): Name of the new branch
75 | - `base_branch` (string, optional): Base branch to create from (defaults to current branch)
76 | - Returns: Confirmation of branch creation
77 | 10. `git_checkout`
78 | - Switches branches
79 | - Inputs:
80 | - `repo_path` (string): Path to Git repository
81 | - `branch_name` (string): Name of branch to checkout
82 | - Returns: Confirmation of branch switch
83 | 11. `git_show`
84 | - Shows the contents of a commit
85 | - Inputs:
86 | - `repo_path` (string): Path to Git repository
87 | - `revision` (string): The revision (commit hash, branch name, tag) to show
88 | - Returns: Contents of the specified commit
89 |
90 | 12. `git_branch`
91 | - List Git branches
92 | - Inputs:
93 | - `repo_path` (string): Path to the Git repository.
94 | - `branch_type` (string): Whether to list local branches ('local'), remote branches ('remote') or all branches('all').
95 | - `contains` (string, optional): The commit sha that branch should contain. Do not pass anything to this param if no commit sha is specified
96 | - `not_contains` (string, optional): The commit sha that branch should NOT contain. Do not pass anything to this param if no commit sha is specified
97 | - Returns: List of branches
98 |
99 | ## Installation
100 |
101 | ### Using uv (recommended)
102 |
103 | When using [`uv`](https://docs.astral.sh/uv/) no specific installation is needed. We will
104 | use [`uvx`](https://docs.astral.sh/uv/guides/tools/) to directly run *mcp-server-git*.
105 |
106 | ### Using PIP
107 |
108 | Alternatively you can install `mcp-server-git` via pip:
109 |
110 | ```
111 | pip install mcp-server-git
112 | ```
113 |
114 | After installation, you can run it as a script using:
115 |
116 | ```
117 | python -m mcp_server_git
118 | ```
119 |
120 | ## Configuration
121 |
122 | ### Usage with Claude Desktop
123 |
124 | Add this to your `claude_desktop_config.json`:
125 |
126 | <details>
127 | <summary>Using uvx</summary>
128 |
129 | ```json
130 | "mcpServers": {
131 | "git": {
132 | "command": "uvx",
133 | "args": ["mcp-server-git", "--repository", "path/to/git/repo"]
134 | }
135 | }
136 | ```
137 | </details>
138 |
139 | <details>
140 | <summary>Using docker</summary>
141 |
142 | * Note: replace '/Users/username' with the a path that you want to be accessible by this tool
143 |
144 | ```json
145 | "mcpServers": {
146 | "git": {
147 | "command": "docker",
148 | "args": ["run", "--rm", "-i", "--mount", "type=bind,src=/Users/username,dst=/Users/username", "mcp/git"]
149 | }
150 | }
151 | ```
152 | </details>
153 |
154 | <details>
155 | <summary>Using pip installation</summary>
156 |
157 | ```json
158 | "mcpServers": {
159 | "git": {
160 | "command": "python",
161 | "args": ["-m", "mcp_server_git", "--repository", "path/to/git/repo"]
162 | }
163 | }
164 | ```
165 | </details>
166 |
167 | ### Usage with VS Code
168 |
169 | For quick installation, use one of the one-click install buttons below...
170 |
171 | [](https://insiders.vscode.dev/redirect/mcp/install?name=git&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-git%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=git&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-git%22%5D%7D&quality=insiders)
172 |
173 | [](https://insiders.vscode.dev/redirect/mcp/install?name=git&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22--rm%22%2C%22-i%22%2C%22--mount%22%2C%22type%3Dbind%2Csrc%3D%24%7BworkspaceFolder%7D%2Cdst%3D%2Fworkspace%22%2C%22mcp%2Fgit%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=git&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22--rm%22%2C%22-i%22%2C%22--mount%22%2C%22type%3Dbind%2Csrc%3D%24%7BworkspaceFolder%7D%2Cdst%3D%2Fworkspace%22%2C%22mcp%2Fgit%22%5D%7D&quality=insiders)
174 |
175 | For manual installation, you can configure the MCP server using one of these methods:
176 |
177 | **Method 1: User Configuration (Recommended)**
178 | Add the configuration to your user-level MCP configuration file. Open the Command Palette (`Ctrl + Shift + P`) and run `MCP: Open User Configuration`. This will open your user `mcp.json` file where you can add the server configuration.
179 |
180 | **Method 2: Workspace Configuration**
181 | Alternatively, you can add the configuration to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.
182 |
183 | > For more details about MCP configuration in VS Code, see the [official VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).
184 |
185 | ```json
186 | {
187 | "servers": {
188 | "git": {
189 | "command": "uvx",
190 | "args": ["mcp-server-git"]
191 | }
192 | }
193 | }
194 | ```
195 |
196 | For Docker installation:
197 |
198 | ```json
199 | {
200 | "mcp": {
201 | "servers": {
202 | "git": {
203 | "command": "docker",
204 | "args": [
205 | "run",
206 | "--rm",
207 | "-i",
208 | "--mount", "type=bind,src=${workspaceFolder},dst=/workspace",
209 | "mcp/git"
210 | ]
211 | }
212 | }
213 | }
214 | }
215 | ```
216 |
217 | ### Usage with [Zed](https://github.com/zed-industries/zed)
218 |
219 | Add to your Zed settings.json:
220 |
221 | <details>
222 | <summary>Using uvx</summary>
223 |
224 | ```json
225 | "context_servers": [
226 | "mcp-server-git": {
227 | "command": {
228 | "path": "uvx",
229 | "args": ["mcp-server-git"]
230 | }
231 | }
232 | ],
233 | ```
234 | </details>
235 |
236 | <details>
237 | <summary>Using pip installation</summary>
238 |
239 | ```json
240 | "context_servers": {
241 | "mcp-server-git": {
242 | "command": {
243 | "path": "python",
244 | "args": ["-m", "mcp_server_git"]
245 | }
246 | }
247 | },
248 | ```
249 | </details>
250 |
251 | ### Usage with [Zencoder](https://zencoder.ai)
252 |
253 | 1. Go to the Zencoder menu (...)
254 | 2. From the dropdown menu, select `Agent Tools`
255 | 3. Click on the `Add Custom MCP`
256 | 4. Add the name (i.e. git) and server configuration from below, and make sure to hit the `Install` button
257 |
258 | <details>
259 | <summary>Using uvx</summary>
260 |
261 | ```json
262 | {
263 | "command": "uvx",
264 | "args": ["mcp-server-git", "--repository", "path/to/git/repo"]
265 | }
266 | ```
267 | </details>
268 |
269 | ## Debugging
270 |
271 | You can use the MCP inspector to debug the server. For uvx installations:
272 |
273 | ```
274 | npx @modelcontextprotocol/inspector uvx mcp-server-git
275 | ```
276 |
277 | Or if you've installed the package in a specific directory or are developing on it:
278 |
279 | ```
280 | cd path/to/servers/src/git
281 | npx @modelcontextprotocol/inspector uv run mcp-server-git
282 | ```
283 |
284 | Running `tail -n 20 -f ~/Library/Logs/Claude/mcp*.log` will show the logs from the server and may
285 | help you debug any issues.
286 |
287 | ## Development
288 |
289 | If you are doing local development, there are two ways to test your changes:
290 |
291 | 1. Run the MCP inspector to test your changes. See [Debugging](#debugging) for run instructions.
292 |
293 | 2. Test using the Claude desktop app. Add the following to your `claude_desktop_config.json`:
294 |
295 | ### Docker
296 |
297 | ```json
298 | {
299 | "mcpServers": {
300 | "git": {
301 | "command": "docker",
302 | "args": [
303 | "run",
304 | "--rm",
305 | "-i",
306 | "--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
307 | "--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
308 | "--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
309 | "mcp/git"
310 | ]
311 | }
312 | }
313 | }
314 | ```
315 |
316 | ### UVX
317 | ```json
318 | {
319 | "mcpServers": {
320 | "git": {
321 | "command": "uv",
322 | "args": [
323 | "--directory",
324 | "/<path to mcp-servers>/mcp-servers/src/git",
325 | "run",
326 | "mcp-server-git"
327 | ]
328 | }
329 | }
330 | }
331 | ```
332 |
333 | ## Build
334 |
335 | Docker build:
336 |
337 | ```bash
338 | cd src/git
339 | docker build -t mcp/git .
340 | ```
341 |
342 | ## License
343 |
344 | This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
345 |
```
--------------------------------------------------------------------------------
/src/filesystem/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Filesystem MCP Server
2 |
3 | Node.js server implementing Model Context Protocol (MCP) for filesystem operations.
4 |
5 | ## Features
6 |
7 | - Read/write files
8 | - Create/list/delete directories
9 | - Move files/directories
10 | - Search files
11 | - Get file metadata
12 | - Dynamic directory access control via [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots)
13 |
14 | ## Directory Access Control
15 |
16 | The server uses a flexible directory access control system. Directories can be specified via command-line arguments or dynamically via [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots).
17 |
18 | ### Method 1: Command-line Arguments
19 | Specify Allowed directories when starting the server:
20 | ```bash
21 | mcp-server-filesystem /path/to/dir1 /path/to/dir2
22 | ```
23 |
24 | ### Method 2: MCP Roots (Recommended)
25 | MCP clients that support [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots) can dynamically update the Allowed directories.
26 |
27 | Roots notified by Client to Server, completely replace any server-side Allowed directories when provided.
28 |
29 | **Important**: If server starts without command-line arguments AND client doesn't support roots protocol (or provides empty roots), the server will throw an error during initialization.
30 |
31 | This is the recommended method, as this enables runtime directory updates via `roots/list_changed` notifications without server restart, providing a more flexible and modern integration experience.
32 |
33 | ### How It Works
34 |
35 | The server's directory access control follows this flow:
36 |
37 | 1. **Server Startup**
38 | - Server starts with directories from command-line arguments (if provided)
39 | - If no arguments provided, server starts with empty allowed directories
40 |
41 | 2. **Client Connection & Initialization**
42 | - Client connects and sends `initialize` request with capabilities
43 | - Server checks if client supports roots protocol (`capabilities.roots`)
44 |
45 | 3. **Roots Protocol Handling** (if client supports roots)
46 | - **On initialization**: Server requests roots from client via `roots/list`
47 | - Client responds with its configured roots
48 | - Server replaces ALL allowed directories with client's roots
49 | - **On runtime updates**: Client can send `notifications/roots/list_changed`
50 | - Server requests updated roots and replaces allowed directories again
51 |
52 | 4. **Fallback Behavior** (if client doesn't support roots)
53 | - Server continues using command-line directories only
54 | - No dynamic updates possible
55 |
56 | 5. **Access Control**
57 | - All filesystem operations are restricted to allowed directories
58 | - Use `list_allowed_directories` tool to see current directories
59 | - Server requires at least ONE allowed directory to operate
60 |
61 | **Note**: The server will only allow operations within directories specified either via `args` or via Roots.
62 |
63 |
64 |
65 | ## API
66 |
67 | ### Tools
68 |
69 | - **read_text_file**
70 | - Read complete contents of a file as text
71 | - Inputs:
72 | - `path` (string)
73 | - `head` (number, optional): First N lines
74 | - `tail` (number, optional): Last N lines
75 | - Always treats the file as UTF-8 text regardless of extension
76 | - Cannot specify both `head` and `tail` simultaneously
77 |
78 | - **read_media_file**
79 | - Read an image or audio file
80 | - Inputs:
81 | - `path` (string)
82 | - Streams the file and returns base64 data with the corresponding MIME type
83 |
84 | - **read_multiple_files**
85 | - Read multiple files simultaneously
86 | - Input: `paths` (string[])
87 | - Failed reads won't stop the entire operation
88 |
89 | - **write_file**
90 | - Create new file or overwrite existing (exercise caution with this)
91 | - Inputs:
92 | - `path` (string): File location
93 | - `content` (string): File content
94 |
95 | - **edit_file**
96 | - Make selective edits using advanced pattern matching and formatting
97 | - Features:
98 | - Line-based and multi-line content matching
99 | - Whitespace normalization with indentation preservation
100 | - Multiple simultaneous edits with correct positioning
101 | - Indentation style detection and preservation
102 | - Git-style diff output with context
103 | - Preview changes with dry run mode
104 | - Inputs:
105 | - `path` (string): File to edit
106 | - `edits` (array): List of edit operations
107 | - `oldText` (string): Text to search for (can be substring)
108 | - `newText` (string): Text to replace with
109 | - `dryRun` (boolean): Preview changes without applying (default: false)
110 | - Returns detailed diff and match information for dry runs, otherwise applies changes
111 | - Best Practice: Always use dryRun first to preview changes before applying them
112 |
113 | - **create_directory**
114 | - Create new directory or ensure it exists
115 | - Input: `path` (string)
116 | - Creates parent directories if needed
117 | - Succeeds silently if directory exists
118 |
119 | - **list_directory**
120 | - List directory contents with [FILE] or [DIR] prefixes
121 | - Input: `path` (string)
122 |
123 | - **list_directory_with_sizes**
124 | - List directory contents with [FILE] or [DIR] prefixes, including file sizes
125 | - Inputs:
126 | - `path` (string): Directory path to list
127 | - `sortBy` (string, optional): Sort entries by "name" or "size" (default: "name")
128 | - Returns detailed listing with file sizes and summary statistics
129 | - Shows total files, directories, and combined size
130 |
131 | - **move_file**
132 | - Move or rename files and directories
133 | - Inputs:
134 | - `source` (string)
135 | - `destination` (string)
136 | - Fails if destination exists
137 |
138 | - **search_files**
139 | - Recursively search for files/directories that match or do not match patterns
140 | - Inputs:
141 | - `path` (string): Starting directory
142 | - `pattern` (string): Search pattern
143 | - `excludePatterns` (string[]): Exclude any patterns.
144 | - Glob-style pattern matching
145 | - Returns full paths to matches
146 |
147 | - **directory_tree**
148 | - Get recursive JSON tree structure of directory contents
149 | - Inputs:
150 | - `path` (string): Starting directory
151 | - `excludePatterns` (string[]): Exclude any patterns. Glob formats are supported.
152 | - Returns:
153 | - JSON array where each entry contains:
154 | - `name` (string): File/directory name
155 | - `type` ('file'|'directory'): Entry type
156 | - `children` (array): Present only for directories
157 | - Empty array for empty directories
158 | - Omitted for files
159 | - Output is formatted with 2-space indentation for readability
160 |
161 | - **get_file_info**
162 | - Get detailed file/directory metadata
163 | - Input: `path` (string)
164 | - Returns:
165 | - Size
166 | - Creation time
167 | - Modified time
168 | - Access time
169 | - Type (file/directory)
170 | - Permissions
171 |
172 | - **list_allowed_directories**
173 | - List all directories the server is allowed to access
174 | - No input required
175 | - Returns:
176 | - Directories that this server can read/write from
177 |
178 | ### Tool annotations (MCP hints)
179 |
180 | This server sets [MCP ToolAnnotations](https://modelcontextprotocol.io/specification/2025-03-26/server/tools#toolannotations)
181 | on each tool so clients can:
182 |
183 | - Distinguish **read‑only** tools from write‑capable tools.
184 | - Understand which write operations are **idempotent** (safe to retry with the same arguments).
185 | - Highlight operations that may be **destructive** (overwriting or heavily mutating data).
186 |
187 | The mapping for filesystem tools is:
188 |
189 | | Tool | readOnlyHint | idempotentHint | destructiveHint | Notes |
190 | |-----------------------------|--------------|----------------|-----------------|--------------------------------------------------|
191 | | `read_text_file` | `true` | – | – | Pure read |
192 | | `read_media_file` | `true` | – | – | Pure read |
193 | | `read_multiple_files` | `true` | – | – | Pure read |
194 | | `list_directory` | `true` | – | – | Pure read |
195 | | `list_directory_with_sizes` | `true` | – | – | Pure read |
196 | | `directory_tree` | `true` | – | – | Pure read |
197 | | `search_files` | `true` | – | – | Pure read |
198 | | `get_file_info` | `true` | – | – | Pure read |
199 | | `list_allowed_directories` | `true` | – | – | Pure read |
200 | | `create_directory` | `false` | `true` | `false` | Re‑creating the same dir is a no‑op |
201 | | `write_file` | `false` | `true` | `true` | Overwrites existing files |
202 | | `edit_file` | `false` | `false` | `true` | Re‑applying edits can fail or double‑apply |
203 | | `move_file` | `false` | `false` | `false` | Move/rename only; repeat usually errors |
204 |
205 | > Note: `idempotentHint` and `destructiveHint` are meaningful only when `readOnlyHint` is `false`, as defined by the MCP spec.
206 |
207 | ## Usage with Claude Desktop
208 | Add this to your `claude_desktop_config.json`:
209 |
210 | Note: you can provide sandboxed directories to the server by mounting them to `/projects`. Adding the `ro` flag will make the directory readonly by the server.
211 |
212 | ### Docker
213 | Note: all directories must be mounted to `/projects` by default.
214 |
215 | ```json
216 | {
217 | "mcpServers": {
218 | "filesystem": {
219 | "command": "docker",
220 | "args": [
221 | "run",
222 | "-i",
223 | "--rm",
224 | "--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
225 | "--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
226 | "--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
227 | "mcp/filesystem",
228 | "/projects"
229 | ]
230 | }
231 | }
232 | }
233 | ```
234 |
235 | ### NPX
236 |
237 | ```json
238 | {
239 | "mcpServers": {
240 | "filesystem": {
241 | "command": "npx",
242 | "args": [
243 | "-y",
244 | "@modelcontextprotocol/server-filesystem",
245 | "/Users/username/Desktop",
246 | "/path/to/other/allowed/dir"
247 | ]
248 | }
249 | }
250 | }
251 | ```
252 |
253 | ## Usage with VS Code
254 |
255 | For quick installation, click the installation buttons below...
256 |
257 | [](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-filesystem%22%2C%22%24%7BworkspaceFolder%7D%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-filesystem%22%2C%22%24%7BworkspaceFolder%7D%22%5D%7D&quality=insiders)
258 |
259 | [](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22--mount%22%2C%22type%3Dbind%2Csrc%3D%24%7BworkspaceFolder%7D%2Cdst%3D%2Fprojects%2Fworkspace%22%2C%22mcp%2Ffilesystem%22%2C%22%2Fprojects%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22--mount%22%2C%22type%3Dbind%2Csrc%3D%24%7BworkspaceFolder%7D%2Cdst%3D%2Fprojects%2Fworkspace%22%2C%22mcp%2Ffilesystem%22%2C%22%2Fprojects%22%5D%7D&quality=insiders)
260 |
261 | For manual installation, you can configure the MCP server using one of these methods:
262 |
263 | **Method 1: User Configuration (Recommended)**
264 | Add the configuration to your user-level MCP configuration file. Open the Command Palette (`Ctrl + Shift + P`) and run `MCP: Open User Configuration`. This will open your user `mcp.json` file where you can add the server configuration.
265 |
266 | **Method 2: Workspace Configuration**
267 | Alternatively, you can add the configuration to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.
268 |
269 | > For more details about MCP configuration in VS Code, see the [official VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).
270 |
271 | You can provide sandboxed directories to the server by mounting them to `/projects`. Adding the `ro` flag will make the directory readonly by the server.
272 |
273 | ### Docker
274 | Note: all directories must be mounted to `/projects` by default.
275 |
276 | ```json
277 | {
278 | "servers": {
279 | "filesystem": {
280 | "command": "docker",
281 | "args": [
282 | "run",
283 | "-i",
284 | "--rm",
285 | "--mount", "type=bind,src=${workspaceFolder},dst=/projects/workspace",
286 | "mcp/filesystem",
287 | "/projects"
288 | ]
289 | }
290 | }
291 | }
292 | ```
293 |
294 | ### NPX
295 |
296 | ```json
297 | {
298 | "servers": {
299 | "filesystem": {
300 | "command": "npx",
301 | "args": [
302 | "-y",
303 | "@modelcontextprotocol/server-filesystem",
304 | "${workspaceFolder}"
305 | ]
306 | }
307 | }
308 | }
309 | ```
310 |
311 | ## Build
312 |
313 | Docker build:
314 |
315 | ```bash
316 | docker build -t mcp/filesystem -f src/filesystem/Dockerfile .
317 | ```
318 |
319 | ## License
320 |
321 | This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
322 |
```