Skip to content

docs: update custom extension project setup #3793

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
blackgirlbytes merged 3 commits into from
Aug 1, 2025
Merged

docs: update custom extension project setup #3793

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bf3e6af
use --lib flag for project setup
dianed-square Aug 1, 2025
3d89158
remove unnecessary note
dianed-square Aug 1, 2025
eebde53
update Goose UI steps, remove screenshot
dianed-square Aug 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file removed documentation/docs/assets/guides/custom-extension-settings.png
View file
Open in desktop
Binary file not shown.
38 changes: 20 additions & 18 deletions documentation/docs/tutorials/custom-extensions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ title: Building Custom Extensions
description: Create your own custom MCP Server to use as a Goose extension
---

import { PanelLeft } from 'lucide-react';

# Building Custom Extensions with Goose


Expand All @@ -28,15 +30,12 @@ The first step is to create a new project using [uv][uv-docs]. We will name our
Run the following commands in your terminal to set up a basic structure for your MCP server:

```bash
uv init mcp-wiki

uv init --lib mcp-wiki
cd mcp-wiki
rm hello.py

mkdir -p src/mcp_wiki
touch src/mcp_wiki/server.py # Your MCP server code (tool, resources, prompts)
touch src/mcp_wiki/__init__.py # Primary CLI entry point
touch src/mcp_wiki/__main__.py # To enable running as a Python module
touch src/mcp_wiki/server.py
touch src/mcp_wiki/__main__.py
```

Your project directory structure should look like this:
Expand All @@ -47,9 +46,10 @@ Your project directory structure should look like this:
├── pyproject.toml
├── src
│ └── mcp_wiki
│ ├── __init__.py
│ ├── __main__.py
│ └── server.py
│ ├── __init__.py # Primary CLI entry point
│ ├── __main__.py # To enable running as a Python module
│ ├── py.typed # Indicates the package supports type hints
│ └── server.py # Your MCP server code (tool, resources, prompts)
└── uv.lock
```

Expand Down Expand Up @@ -247,24 +247,26 @@ build-backend = "hatchling.build"

To add your MCP server as an extension in Goose:

1. Go to `Settings > Extensions > Add`.
2. Set the `Type` to `StandardIO`.
3. Provide the ID, name, and description for your extension.
4. In the `Command` field, provide the absolute path to your executable. For example:
1. Click the <PanelLeft className="inline" size={16} /> button in the top-left to open the sidebar
2. Click `Extensions` in the sidebar
3. Set the `Type` to `STDIO`
4. Provide a name and description for your extension
5. In the `Command` field, provide the absolute path to your executable:
```plaintext
uv run /full/path/to/mcp-wiki/.venv/bin/mcp-wiki
```

Alternatively in Step 3, you can also publish your package to pypi. Once published, the server can be run directly using uvx. For example:
For example:
```plaintext
uv run /Users/smohammed/Development/mcp/mcp-wiki/.venv/bin/mcp-wiki
```

For the purposes on this guide, we'll run the local version. Alternatively, you can publish your package to PyPI. Once published, the server can be run directly using `uvx`. For example:

```
uvx mcp-wiki
```

For the purposes on this guide, we will show you how to run the local version. 

![Goose Settings for Adding Custom Extension](../assets/guides/custom-extension-settings.png)

---

## Step 6: Use Your Extension in Goose
Expand Down