kintone

Um servidor MCP

Documentação

Exemplo de Servidor MCP kintone (Python3)

Esta é uma implementação de exemplo de um servidor MCP (Model Context Protocol) para integração com kintone. Este servidor permite que assistentes de IA (como Claude) leiam e manipulem dados do kintone.

Principais Recursos

🔐 Autenticação Segura: Suporta tanto autenticação por token de API quanto por senha
📊 Operações CRUD Completas: Criar, ler, atualizar e excluir registros
📄 Paginação Automática: Processa eficientemente grandes volumes de registros
🔍 Recursos Avançados de Consulta: Suporte completo à sintaxe de consulta do kintone
📎 Gerenciamento de Arquivos: Upload e download de arquivos
💬 Recurso de Comentários: Adicionar e obter comentários em registros
🔄 Gerenciamento de Status: Atualização de status do gerenciamento de processos
🚀 Processamento Assíncrono: Respostas rápidas e uso eficiente de recursos
🛡️ Tratamento Robusto de Erros: Mensagens de erro detalhadas e tratamento adequado de exceções
🌐 Suporte à Internacionalização: Suporte a campos multilíngues

Ferramentas Disponíveis

Operações com Registros

Nome da Ferramenta	Descrição	Uso Principal
`get_record`	Obter um único registro	Obter informações detalhadas de um registro específico
`get_records`	Obter lista de registros (com paginação)	Pesquisar e obter registros que atendam às condições
`get_all_records`	Obter automaticamente todos os registros	Obter grandes volumes de registros (paginação automática)
`add_record`	Adicionar um único registro	Criar um novo registro
`add_records`	Adicionar vários registros em lote (máx. 100)	Criar registros eficientemente por processamento em lote
`update_record`	Atualizar um único registro	Atualizar informações de um registro existente
`update_records`	Atualizar vários registros em lote (máx. 100)	Atualizar registros eficientemente por processamento em lote

Operações com Comentários e Status

Nome da Ferramenta	Descrição	Uso Principal
`get_comments`	Obter comentários de um registro	Verificar histórico de comunicação
`add_comment`	Adicionar comentário a um registro	Publicar comentários com menções
`update_status`	Atualizar status de um registro	Avançar fluxo de trabalho
`update_statuses`	Atualizar status de vários registros em lote	Processamento eficiente de fluxo de trabalho

Gerenciamento de Arquivos e Aplicativos

Nome da Ferramenta	Descrição	Uso Principal
`upload_file`	Upload de arquivo	Registrar arquivos anexados
`download_file`	Download de arquivo	Obter arquivos anexados
`get_app`	Obter informações do aplicativo	Verificar configurações do aplicativo
`get_apps`	Pesquisar e obter lista de aplicativos	Explorar aplicativos disponíveis
`get_form_fields`	Obter configurações dos campos do formulário	Entender a estrutura do aplicativo

Pré-requisitos

Python 3.12 ou superior
uv (recomendado)
Permissão de acesso ao ambiente kintone
Token de API ou credenciais de usuário

Configuração do Cliente MCP

Configuração do Claude Desktop

Para usar este servidor com o Claude Desktop, adicione o seguinte ao arquivo de configuração.

Localização do arquivo de configuração

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Usando uvx (recomendado)

Configuração para executar diretamente do GitHub:

{
  "mcpServers": {
    "kintone": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/r3-yamauchi/kintone-mcp-server-python3.git",
        "kintone-mcp-server-python3"
      ],
      "env": {
        "KINTONE_DOMAIN": "your-subdomain.cybozu.com",
        "KINTONE_USERNAME": "your-username",
        "KINTONE_PASSWORD": "your-password"
      }
    }
  }
}

Importante:

Substitua KINTONE_DOMAIN pelo valor real (exemplo: dev-demo.cybozu.com)
A autenticação usará autenticação por senha se nome de usuário e senha forem fornecidos; caso contrário, será usada autenticação por token de API
As variáveis de ambiente são descritas diretamente em claude_desktop_config.json
Reinicie o Claude Desktop após alterar a configuração

Configuração do VS Code

Ao usar a extensão MCP do VS Code:

{
  "mcp.servers": {
    "kintone": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/r3-yamauchi/kintone-mcp-server-python3.git",
        "kintone-mcp-server-python3"
      ],
      "env": {
        "KINTONE_DOMAIN": "your-subdomain.cybozu.com",
        "KINTONE_API_TOKEN": "your-api-token"
      }
    }
  }
}

Exemplo de configuração para múltiplos ambientes

Ao gerenciar ambientes de produção e desenvolvimento separadamente:

{
  "mcpServers": {
    "kintone-prod": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/r3-yamauchi/kintone-mcp-server-python3.git",
        "kintone-mcp-server-python3"
      ],
      "env": {
        "KINTONE_DOMAIN": "your-subdomain.cybozu.com",
        "KINTONE_API_TOKEN": "prod-api-token"
      }
    },
    "kintone-dev": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/r3-yamauchi/kintone-mcp-server-python3.git",
        "kintone-mcp-server-python3"
      ],
      "env": {
        "KINTONE_DOMAIN": "your-subdomain.cybozu.com",
        "KINTONE_USERNAME": "dev-user",
        "KINTONE_PASSWORD": "dev-password"
      }
    }
  }
}

Pontos de configuração

Vantagens do uvx
- Não requer instalação prévia
- Sempre executa a versão mais recente
- Evita conflitos de dependências
Avisos de segurança
- É necessário salvar informações confidenciais (nome de usuário, senha, token de API) em texto simples em claude_desktop_config.json para acessar o kintone
- Não compartilhe este arquivo com outras pessoas
- Tenha cuidado para não fazer commit em repositórios Git

Solução de Problemas

Problemas comuns e soluções

Erro de conexão

Error: Failed to connect to kintone

Soluções:

Verifique se KINTONE_DOMAIN está correto (exemplo: dev-demo.cybozu.com)
Verifique a conexão de rede
Verifique as configurações do firewall

Erro de autenticação

Error: Authentication failed (401)

Soluções:

Verifique se o nome de usuário, senha ou token de API estão corretos
Verifique se o token de API possui as permissões necessárias
Verifique se o token de API está habilitado nas configurações do aplicativo

Erro de permissão

Error: Permission denied (403)

Soluções:

Verifique se o usuário tem permissão de acesso ao aplicativo
Verifique se as permissões necessárias foram concedidas ao token de API
Verifique as permissões de acesso aos registros

Modo de depuração

Para gerar logs detalhados:

export LOG_LEVEL=DEBUG
uvx --from git+https://github.com/r3-yamauchi/kintone-mcp-server-python3.git kintone-mcp-server-python3

Instalação local do código-fonte

# リポジトリをクローン
git clone https://github.com/r3-yamauchi/kintone-mcp-server-python3.git
cd kintone-mcp-server-python3

# 依存関係をインストール
pip install -e .

# 実行
python -m kintone_mcp_server_python3

Exemplos de uso

Uso básico

get_records

Obtém registros do aplicativo kintone com recurso de paginação.

Parâmetros:

app (obrigatório): ID do aplicativo
query (opcional): String de consulta para filtrar registros
fields (opcional): Lista de códigos de campo a serem obtidos
limit (opcional): Número máximo de registros a obter (padrão: 100, máximo: 500)
offset (opcional): Deslocamento para paginação (padrão: 0)

Exemplo de uso:

{
  "tool": "get_records",
  "arguments": {
    "app": 123,
    "query": "Status = \"Open\"",
    "fields": ["Title", "Status", "Created_datetime"],
    "limit": 100
  }
}

get_all_records

Obtém todos os registros do aplicativo kintone (processa a paginação automaticamente).

Parâmetros:

app (obrigatório): ID do aplicativo
query (opcional): String de consulta para filtrar registros
fields (opcional): Lista de códigos de campo a serem obtidos

Exemplo de uso:

{
  "tool": "get_all_records",
  "arguments": {
    "app": 123,
    "query": "Created_datetime > \"2024-01-01\"",
    "fields": ["Title", "Status"]
  }
}

get_apps

Pesquisa e obtém informações dos aplicativos kintone.

Parâmetros:

name (opcional): Pesquisa por correspondência parcial do nome do aplicativo (não diferencia maiúsculas de minúsculas)
ids (opcional): Lista de IDs de aplicativos a obter
codes (opcional): Lista de códigos de aplicativos a obter (correspondência exata, diferencia maiúsculas de minúsculas)
space_ids (opcional): Filtrar por ID de espaço
limit (opcional): Número máximo de aplicativos a obter (padrão: 100, máximo: 100)
offset (opcional): Deslocamento para paginação (padrão: 0)

Exemplo de uso:

{
  "tool": "get_apps",
  "arguments": {
    "name": "顧客",
    "limit": 50
  }
}

Exemplo de resposta:

{
  "apps": [
    {
      "appId": "123",
      "code": "CUSTOMER_APP",
      "name": "顧客管理",
      "description": "顧客情報を管理するアプリです",
      "spaceId": "10",
      "createdAt": "2024-01-01T00:00:00Z",
      "creator": {
        "code": "user1",
        "name": "山田太郎"
      },
      "modifiedAt": "2024-01-15T10:30:00Z",
      "modifier": {
        "code": "user2",
        "name": "佐藤花子"
      }
    }
  ],
  "count": 1
}

get_record

Obtém um único registro.

Parâmetros:

app (obrigatório): ID do aplicativo
id (obrigatório): ID do registro

Exemplo de uso:

{
  "tool": "get_record",
  "arguments": {
    "app": 123,
    "id": 456
  }
}

add_record

Adiciona um único registro ao aplicativo kintone.

Parâmetros:

app (obrigatório): ID do aplicativo
record (obrigatório): Objeto com códigos de campo e valores

Exemplo de uso:

{
  "tool": "add_record",
  "arguments": {
    "app": 123,
    "record": {
      "Title": {"value": "新しいタスク"},
      "Status": {"value": "未着手"},
      "Assignee": {"value": [{"code": "user1"}]}
    }
  }
}

add_records

Adiciona vários registros em lote (máximo de 100).

Parâmetros:

app (obrigatório): ID do aplicativo
records (obrigatório): Matriz de dados de registros

Exemplo de uso:

{
  "tool": "add_records",
  "arguments": {
    "app": 123,
    "records": [
      {
        "Title": {"value": "タスク1"},
        "Status": {"value": "未着手"}
      },
      {
        "Title": {"value": "タスク2"},
        "Status": {"value": "進行中"}
      }
    ]
  }
}

update_record

Atualiza um único registro.

Parâmetros:

app (obrigatório): ID do aplicativo
id (opcional): ID do registro (obrigatório informar id ou update_key)
update_key (opcional): Campo e valor que servirão como chave de atualização
record (obrigatório): Campos e valores a atualizar
revision (opcional): Número da revisão (para bloqueio otimista)

Exemplo de uso:

{
  "tool": "update_record",
  "arguments": {
    "app": 123,
    "id": 456,
    "record": {
      "Status": {"value": "完了"},
      "CompletedDate": {"value": "2024-12-07"}
    }
  }
}

update_records

Atualiza vários registros em lote (máximo de 100).

Parâmetros:

app (obrigatório): ID do aplicativo
records (obrigatório): Matriz de dados de atualização

Exemplo de uso:

{
  "tool": "update_records",
  "arguments": {
    "app": 123,
    "records": [
      {
        "id": 456,
        "record": {"Status": {"value": "完了"}}
      },
      {
        "id": 789,
        "record": {"Status": {"value": "保留"}}
      }
    ]
  }
}

get_comments

Obtém comentários de um registro.

Parâmetros:

app (obrigatório): ID do aplicativo
record (obrigatório): ID do registro
order (opcional): Ordem de classificação ("asc" ou "desc", padrão: "desc")
offset (opcional): Deslocamento (padrão: 0)
limit (opcional): Número de itens a obter (máximo 10, padrão: 10)

Exemplo de uso:

{
  "tool": "get_comments",
  "arguments": {
    "app": 123,
    "record": 456,
    "order": "desc",
    "limit": 5
  }
}

add_comment

Adiciona um comentário a um registro.

Parâmetros:

app (obrigatório): ID do aplicativo
record (obrigatório): ID do registro
text (obrigatório): Texto do comentário
mentions (opcional): Matriz de informações de menção

Exemplo de uso:

{
  "tool": "add_comment",
  "arguments": {
    "app": 123,
    "record": 456,
    "text": "作業が完了しました。",
    "mentions": [
      {"code": "user1", "type": "USER"}
    ]
  }
}

update_status

Atualiza o status de um registro.

Parâmetros:

app (obrigatório): ID do aplicativo
id (obrigatório): ID do registro
action (obrigatório): Nome da ação
assignee (opcional): Nome de login do responsável
revision (opcional): Número da revisão

Exemplo de uso:

{
  "tool": "update_status",
  "arguments": {
    "app": 123,
    "id": 456,
    "action": "承認する",
    "assignee": "user2"
  }
}

update_statuses

Atualiza o status de vários registros em lote (máximo de 100).

Parâmetros:

app (obrigatório): ID do aplicativo
records (obrigatório): Matriz de dados de atualização de status

Exemplo de uso:

{
  "tool": "update_statuses",
  "arguments": {
    "app": 123,
    "records": [
      {
        "id": 456,
        "action": "承認する"
      },
      {
        "id": 789,
        "action": "却下する"
      }
    ]
  }
}

upload_file

Faz upload de um arquivo para o kintone.

Parâmetros:

file_path (obrigatório): Caminho do arquivo a ser enviado

Exemplo de uso:

{
  "tool": "upload_file",
  "arguments": {
    "file_path": "/path/to/document.pdf"
  }
}

Exemplo de resposta:

{
  "fileKey": "20241207103000-1234567890ABCDEF"
}

download_file

Baixa um arquivo do kintone.

Parâmetros:

file_key (obrigatório): Chave do arquivo
save_path (obrigatório): Caminho do arquivo de destino

Exemplo de uso:

{
  "tool": "download_file",
  "arguments": {
    "file_key": "20241207103000-1234567890ABCDEF",
    "save_path": "/path/to/save/document.pdf"
  }
}

get_app

Obtém informações detalhadas do aplicativo.

Parâmetros:

id (obrigatório): ID do aplicativo

Exemplo de uso:

{
  "tool": "get_app",
  "arguments": {
    "id": 123
  }
}

get_form_fields

Obtém as configurações dos campos do formulário do aplicativo.

Parâmetros:

app (obrigatório): ID do aplicativo
lang (opcional): Código do idioma (exemplo: "ja", "en")

Exemplo de uso:

{
  "tool": "get_form_fields",
  "arguments": {
    "app": 123,
    "lang": "ja"
  }
}

Exemplo de resposta:

{
  "properties": {
    "Title": {
      "type": "SINGLE_LINE_TEXT",
      "code": "Title",
      "label": "タイトル",
      "required": true
    },
    "Status": {
      "type": "DROP_DOWN",
      "code": "Status",
      "label": "ステータス",
      "options": {
        "未着手": {"label": "未着手", "index": "0"},
        "進行中": {"label": "進行中", "index": "1"},
        "完了": {"label": "完了", "index": "2"}
      }
    }
  },
  "revision": "5"
}

Desenvolvimento

Configuração do ambiente de desenvolvimento

# リポジトリをクローン
git clone https://github.com/r3-yamauchi/kintone-mcp-server-python3.git
cd kintone-mcp-server-python3

# 仮想環境の作成（推奨）
python -m venv venv
source venv/bin/activate  # macOS/Linux
# venv\Scripts\activate  # Windows

# 開発用依存関係をインストール
pip install -e ".[dev]"

# 環境変数の設定
cp .env.example .env
# .envファイルを編集して必要な設定を追加

# pre-commitフックの設定（推奨）
pre-commit install

Testes

# すべてのテストを実行
pytest

# カバレッジレポート付きでテスト実行
pytest --cov=kintone_mcp_server_python3 --cov-report=html

# 特定のテストファイルを実行
pytest tests/test_auth.py

# 特定のテストを実行
pytest tests/test_auth.py::test_api_token_auth -v

Gerenciamento de qualidade de código

# コードフォーマット（Black）
black src tests

# リンティング（Ruff）
ruff check src tests
ruff check src tests --fix  # 自動修正

# 型チェック（MyPy）
mypy src

# すべてのチェックを実行
make lint  # Makefileがある場合
# または
black src tests && ruff check src tests && mypy src

Procedimento de lançamento

Atualizar o número da versão (pyproject.toml)
Atualizar o histórico de alterações (CHANGELOG.md)
Executar os testes e confirmar o sucesso

Verificação de qualidade do código:

black src tests
ruff check src tests
mypy src

Enviar para o GitHub:

git add .
git commit -m "Release v0.1.0"
git tag v0.1.0
git push origin main --tags

Criar notas de versão no GitHub (opcional)

FAQ

P: Posso usar vários ambientes kintone simultaneamente?

R: Sim, você pode definir várias instâncias de servidor na configuração do cliente MCP. Dê nomes diferentes para cada ambiente (exemplo: kintone-prod, kintone-dev).

P: Posso obter informações de campos em idiomas diferentes do japonês?

R: Sim, usando o parâmetro lang na ferramenta get_form_fields, você pode obter informações de campos em inglês (en), chinês (zh), espanhol (es), entre outros.

Autor

r3-yamauchi

Licença

Este projeto é publicado sob a licença MIT. Consulte o arquivo LICENSE para obter detalhes.

Riscos ao usar o Servidor MCP

Ao usar um servidor MCP criado e implementado por terceiros, lembre-se sempre de que existem certos riscos.

Situação atual do kintone AI Lab e do Servidor MCP para kintone

"kintone" é uma marca registrada da Cybozu, Inc.

O conteúdo aqui descrito tem finalidade informativa e não oferece suporte individual. Observe que não podemos responder a perguntas sobre configurações ou problemas em que o ambiente não funcione corretamente.