Official MCP server for NervusDB - Code knowledge graph with repomix integration
- Code Knowledge Graph: Build cross-language code knowledge graphs using
@nervusdb/coreandrepomix - Project Insights: Analyze code impact, find related files, and explore project structure
- Workflow Automation: Task management with branch creation and PR submission
- Code Operations: Read, write files, and run tests with safety checks
- Database Tools: Query and maintain the knowledge graph index
- Shadow Index Strategy: Ensures reliable indexing with fingerprint validation
- Node.js 20.0.0 or higher
- pnpm 8.0.0 or higher
Install Dependencies
pnpm installRun the Server
# For development
pnpm start:stdio
# Build for production
pnpm buildIndex a Project
pnpm synapse:index -p /path/to/your/projectAdd to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"nervusdb-mcp": {
"command": "npx",
"args": ["-y", "@nervusdb/mcp"]
}
}
}Alternatively, if you've installed the package globally:
{
"mcpServers": {
"nervusdb-mcp": {
"command": "nervusdb-mcp"
}
}
}Installation Options:
# Option 1: Use npx (recommended, no installation needed)
# Just add the config above, Claude will run it automatically
# Option 2: Install globally for faster startup
npm install -g @nervusdb/mcpWorkflow tools (workflow.submitForReview) require GitHub authentication to create pull requests. The server supports 3 authentication methods with automatic fallback:
Method 1: Environment Variables (Recommended for CI/CD)
# Set GITHUB_TOKEN or GH_TOKEN
export GITHUB_TOKEN=ghp_your_personal_access_token
# Or in your shell profile (~/.zshrc or ~/.bashrc)
echo 'export GITHUB_TOKEN=ghp_xxx' >> ~/.zshrcMethod 2: GitHub CLI (Recommended for Local Development)
# Install gh CLI
brew install gh # macOS
# Or see https://cli.github.com/ for other platforms
# Authenticate
gh auth loginMethod 3: Claude Desktop Configuration
Add environment variables to Claude Desktop config:
{
"mcpServers": {
"nervusdb-mcp": {
"command": "npx",
"args": ["-y", "@nervusdb/mcp"],
"env": {
"GITHUB_TOKEN": "ghp_your_personal_access_token"
}
}
}
}Authentication Priority:
GITHUB_TOKENenvironment variable (highest priority)GH_TOKENenvironment variablegh auth tokencommand (if gh CLI is authenticated)
If no authentication is available, workflow tools will provide clear error messages with setup instructions.
The NervusDB MCP server provides 13 tools across 4 categories:
workflow.startTask- Create task branch and update ledgerworkflow.submitForReview- Push branch and create pull request (requires GitHub authentication)
project.getStructure- Get project file structure with statisticsproject.analyzeImpact- Analyze code impact based on knowledge graphproject.findRelatedFiles- Find files related to a target fileproject.readFile- Read arbitrary file content
code.readFile- Read project file contentcode.writeFile- Write content to project file (requires confirmation)code.runTests- Run tests using Vitest and return results
db.getStats- Get index metadata and statisticsdb.query- Execute typed or raw queries against knowledge graphdb.rebuildIndex- Rebuild project index with telemetrydb.getHealth- Check index health with fingerprint validation
// 1. Start a new task
workflow.startTask({
taskId: '42',
owner: 'alice',
designDoc: 'docs/design/feature-42.md',
});
// 2. Analyze code impact
project.analyzeImpact({
projectPath: '/workspace/my-project',
functionName: 'calculateTotal',
limit: 20,
});
// 3. Read a file
code.readFile({
projectPath: '/workspace/my-project',
file: 'src/services/orderService.ts',
});
// 4. Run tests
code.runTests({
projectPath: '/workspace/my-project',
filter: 'orderService',
});
// 5. Query the knowledge graph
db.query({
projectPath: '/workspace/my-project',
query: {
type: 'typed',
filter: { predicate: 'CONTAINS' },
options: { limit: 100 },
},
});
// 6. Submit for review
workflow.submitForReview({
confirm: true,
title: 'feat: optimize order calculation',
reviewers: ['bob'],
});- Indexing: Uses
repomixto collect project files and@nervusdb/coreto build a knowledge graph - Storage: Maintains shadow indices with fingerprint validation for data integrity
- Query: Provides typed and raw query interfaces to explore code relationships
- Workflow: Integrates with Git workflows for task management
nervusdb-mcp/
├── src/
│ ├── server/ # MCP server implementation
│ ├── tools/ # Tool implementations (workflow, project, code, db)
│ ├── services/ # Business logic services
│ ├── domain/ # Core domain logic (indexing, query)
│ └── utils/ # Shared utilities
├── bin/ # CLI executables
├── docs/ # Documentation
└── tests/ # Test suites
# Install dependencies
pnpm install
# Run tests
pnpm test
# Check code quality
pnpm check
# Build for production
pnpm build- Tools Overview - Detailed documentation for all 13 tools
- Architecture Design
- Quality Guidelines
- Build and Release
See CONTRIBUTING.md for development guidelines.
MIT