Este guia fornece instruções testadas para instalar o Discourse MCP no OpenCode CLI. Se você estiver usando um cliente MCP diferente, também escrevi guias para o Codex CLI.
USE SEU LLM! LLMs são muito bons em seguir instruções e podem fazer a configuração para você. Aponte o LLM para este guia por URL e peça para ele fazer a configuração. Você também pode pedir para ele explicar quaisquer etapas que não entendeu.
Pré-requisitos:
- Node.js instalado (24 LTS recomendado)
- OpenCode CLI instalado
- Acesso ao fórum Discourse pretendido como usuário comum (não é necessário ser administrador!)
É importante perceber que existem três componentes separados aqui:
- O fórum Discourse remoto, que é a fonte de dados e o alvo das ações.
- O servidor Discourse MCP, que é uma ferramenta de código aberto executada localmente que se conecta ao Discourse e fornece uma API para o OpenCode interagir com o Discourse. Isso é instalado como um pacote NPX e iniciado sob demanda pelo OpenCode CLI.
- OpenCode CLI, que é o cliente MCP que se conecta ao servidor MCP e fornece a interface para interagir com o Discourse através da API do MCP.
1. Gerar a chave de API de Usuário
Isso autenticará você no Discourse e é como você obterá sua chave de API. npx baixará e executará o código, nada precisa ser instalado no sentido tradicional.
Em um terminal, execute:
npx @discourse/mcp@latest generate-user-api-key \
--site =DISCOURSE-FORUM= \
--save-to =PROFILE-PATH/=NAME=.json
Exemplo:
npx @discourse/mcp@latest generate-user-api-key \
--site https://meta.discourse.org \
--save-to ~/.config/opencode/discourse-profiles/meta.json
Aprove o consentimento do navegador e copie de volta os dados criptografados, o que prova sua capacidade de fazer login e gera uma chave de API que é salva em =PROFILE-PATH= para uso pelo servidor MCP.
A chave de API terá o mesmo nível de acesso ao fórum que você tem como usuário.
2. Adicionar o servidor MCP ao OpenCode CLI
Edite seu arquivo de configuração do OpenCode em ~/.config/opencode/opencode.jsonc e adicione a seguinte entrada à seção mcp:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
// ... outros servidores MCP ...
"discourse-=NAME=-mcp": {
"type": "local",
"command": [
"npx",
"-y",
"@discourse/mcp@latest",
"--profile",
"=PROFILE-PATH/=NAME=.json",
],
"enabled": true,
"environment": {},
},
},
}
Exemplo:
"discourse-meta-mcp": {
"type": "local",
"command": [
"npx",
"-y",
"@discourse/mcp@latest",
"--profile",
"/home/marcus/.config/opencode/discourse-profiles/meta.json"
],
"enabled": true,
"environment": {},
},
O servidor MCP será iniciado sob demanda com npx pelo OpenCode CLI quando você iniciar o OpenCode. Ele é configurado para usar o perfil em =PROFILE-PATH= e, por padrão, é somente leitura.
3. Reiniciar o OpenCode CLI
Reinicie totalmente o OpenCode para que ele recarregue a configuração e se conecte ao servidor MCP.
Se ele iniciar sem erros, o servidor Discourse MCP está funcionando. Você pode pedir ao OpenCode para se referir ao seu fórum Discourse para obter informações — especialmente informações às quais você tem acesso, mas que não são públicas — isso verificará se ele está se conectando como você.
Gerenciando Múltiplas Instâncias do Discourse
Você pode adicionar vários fóruns Discourse repetindo o processo com diferentes arquivos de perfil e nomes de servidor MCP:
"discourse-meta-mcp": {
"type": "local",
"command": [
"npx", "-y", "@discourse/mcp@latest",
"--profile", "/home/username/.config/opencode/discourse-profiles/meta.json"
],
"enabled": true,
"environment": {},
},
"discourse-mycommunity-mcp": {
"type": "local",
"command": [
"npx", "-y", "@discourse/mcp@latest",
"--profile", "/home/username/.config/opencode/discourse-profiles/mycommunity.json"
],
"enabled": true,
"environment": {},
},
Arquivos de Configuração
Existem dois arquivos principais:
-
=OPENCODE-CONFIG=- Arquivo de configuração do OpenCode CLI em~/.config/opencode/opencode.jsonc, que inclui as configurações do servidor MCP. -
=PROFILE-PATH=- O perfil para o servidor Discourse MCP, que inclui a chave de API e outras configurações para conexão com o Discourse.
Configurações do OpenCode
As configurações para conectar ao servidor MCP estão em =OPENCODE-CONFIG= (tipicamente ~/.config/opencode/opencode.jsonc):
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"discourse-=NAME=-mcp": {
"type": "local",
"command": [
"npx",
"-y",
"@discourse/mcp@latest",
"--profile",
"=PROFILE-PATH/=NAME=.json",
],
"enabled": true,
"environment": {},
},
},
}
Documentação das Configurações do MCP do OpenCode: Documentação do OpenCode
Configurações do Discourse MCP
As configurações para o próprio servidor Discourse MCP estão em =PROFILE-PATH/=NAME=.json=:
{
"auth_pairs": [
{
"site": "=DISCOURSE-FORUM=",
"user_api_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"user_api_client_id": "discourse-mcp"
}
]
}
Documentação das configurações do Discourse MCP: GitHub - discourse/discourse-mcp
Práticas Recomendadas de Segurança
É recomendável:
- Armazenar arquivos de perfil em um diretório dedicado (ex:
~/.config/opencode/discourse-profiles/) - Adicionar este diretório ao
.gitignorese você estiver rastreando seus dotfiles em controle de versão - Usar nomes descritivos para seus arquivos de perfil (ex:
meta.json,mycommunity.json) - Manter as chaves de API privadas - elas têm o mesmo nível de acesso que sua conta de usuário
Solução de Problemas
- Problemas de conexão: Verifique se o caminho do perfil em
opencode.jsoncestá correto e se o arquivo existe - Erros de autorização: Verifique se a chave de API não foi revogada nas preferências de usuário do seu Discourse
- Erros de permissão: Garanta que você tem as permissões necessárias na instância do Discourse
- Reinicialização necessária: Alterações em
opencode.jsoncexigem a reinicialização do OpenCode CLI