Serena Integration

Name: 1MCP Agent
Author: 1MCP

🧠 Semantic Intelligence: Leverage Serena's powerful semantic code analysis with 1MCP's dynamic template system for project-aware workflows

Overview

Serena is a semantic code analysis toolkit that provides LSP-powered understanding of your codebase. It offers symbol-level operations, cross-reference analysis, and intelligent code navigation across 30+ programming languages.

Why Use Serena with 1MCP Templates?

Key Capabilities

Symbol-Level Operations: Find, reference, rename, and manipulate code symbols
Multi-Language Support: Python, TypeScript, Java, Rust, Go, C/C++, and 30+ more
LSP-Powered Analysis: Leverages Language Server Protocol for accurate understanding
Project Indexing: Fast symbol lookup for large codebases
Web Dashboard: Visual project exploration at http://localhost:24282/dashboard

Quick Start

Basic Static Configuration

Add Serena to your mcp.json with a fixed project path:

json

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena",
        "serena",
        "start-mcp-server",
        "--project",
        "/absolute/path/to/your/project",
        "--context",
        "claude-code"
      ],
      "tags": ["filesystem", "search", "semantic"]
    }
  }
}

Template-Based Configuration (Recommended)

Use templates for automatic project detection:

json

{
  "mcpTemplates": {
    "project-serena": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena",
        "serena",
        "start-mcp-server",
        "--project",
        "{{project.path}}",
        "--context",
        "claude-code"
      ],
      "tags": ["filesystem", "search", "semantic"]
    }
  }
}

How it works: When a client connects, 1MCP automatically:

Detects the current project directory
Renders {{project.path}} with the actual path
Launches Serena configured for that specific project
Provides project-aware semantic analysis tools

Template Variables

Project Path Injection

Important: 1MCP automatically shares the same Serena instance when the rendered template configuration is identical. This means:

Multiple AI clients/sessions on the same machine working on the same project with the same context share one Serena instance
Each unique project path gets its own dedicated Serena instance
Different contexts (e.g., claude-code vs ide) get separate instances

Example: If you open multiple terminal windows on your development machine running Claude Code CLI, all connected to the same project, they share one Serena instance with the claude-code context. If you then open Cursor (also on the same machine) for the same project, it gets a separate instance with ide context.

Note: Serena requires local file access to read code, configuration, and cache files. Each developer on their own machine will have their own Serena instance, even when working on the same project.

Benefits:

Resource Efficiency: Reduced memory and CPU usage on your local machine
Shared Symbol Index: Faster analysis after the first AI client connects
Consistent State: All AI clients on the same machine see the same semantic understanding

Context-Aware Configuration

Serena's --context parameter controls which tools are available based on the client type. Use template conditionals to select the appropriate context:

Available Context Types

Context	Use Case	Tools Available
`claude-code`	Claude Code CLI	Optimized tool set, disables IDE-redundant features
`ide`	VSCode, Cursor, IDEs	Reduced tools to avoid duplication with IDE features
`codex`	Codex CLI	Required for Codex compatibility
Custom	User-defined	Create via Serena's config system

Client-Aware Context Selection

Automatically choose context based on the connecting client:

json

{
  "mcpTemplates": {
    "smart-serena": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena",
        "serena",
        "start-mcp-server",
        "--project",
        "{{project.path}}",
        "--context",
        "{{#if (eq transport.client.name 'cursor')}}ide{{else}}claude-code{{/if}}"
      ],
      "tags": ["filesystem", "search", "semantic"]
    }
  }
}

How it works:

Cursor or VSCode clients get ide context (avoids tool duplication)
All other clients get claude-code context (full tool set)

Multi-Client Context Mapping

Handle multiple IDE clients with complex conditionals:

json

{
  "mcpTemplates": {
    "client-aware-serena": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena",
        "serena",
        "start-mcp-server",
        "--project",
        "{{project.path}}",
        "--context",
        "{{#if (or (eq transport.client.name 'cursor') (eq transport.client.name 'vscode'))}}ide{{else}}claude-code{{/if}}"
      ],
      "tags": ["filesystem", "search", "semantic"]
    }
  }
}

Project-Level Configuration

Using .1mcprc for Custom Context

Define custom metadata in .1mcprc and reference it in templates:

.1mcprc in your project root:

json

{
  "preset": "dev-tools",
  "tags": ["backend", "python"],
  "context": {
    "projectId": "myapp-backend",
    "environment": "development",
    "custom": {
      "serenaContext": "claude-code",
      "enableDashboard": true
    }
  }
}

Template using custom context:

json

{
  "mcpTemplates": {
    "custom-serena": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena",
        "serena",
        "start-mcp-server",
        "--project",
        "{{project.path}}",
        "--context",
        "{{project.custom.serenaContext}}",
        "--open-web-dashboard",
        "{{project.custom.enableDashboard}}"
      ],
      "tags": ["filesystem", "search", "semantic"]
    }
  }
}

Serena's Own Configuration

Serena maintains its own configuration separate from 1MCP templates:

Global config: ~/.serena/serena_config.yml
Project config: .serena/project.yml (created via serena project create)

Setting up Serena project config:

bash

# Navigate to your project
cd /path/to/your/project

# Initialize Serena project with indexing
serena project create --index

# This creates .serena/project.yml with project-specific settings

Important: 1MCP templates configure the Serena server instance (CLI arguments), while Serena's config files control analysis behavior (indexing preferences, language settings).

Complete Examples

Example 1: Multi-Environment Setup

Enable semantic analysis in development, disable in production:

json

{
  "mcpTemplates": {
    "env-aware-serena": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena",
        "serena",
        "start-mcp-server",
        "--project",
        "{{project.path}}",
        "--context",
        "claude-code"
      ],
      "disabled": "{{#if (eq project.environment 'production')}}true{{else}}false{{/if}}",
      "tags": ["filesystem", "search", "semantic", "development"]
    }
  }
}

Use case: Prevent resource-intensive semantic analysis in production environments while keeping it available for development.

Example 2: Dashboard Control

Control web dashboard based on environment:

json

{
  "mcpTemplates": {
    "dashboard-controlled-serena": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena",
        "serena",
        "start-mcp-server",
        "--project",
        "{{project.path}}",
        "--context",
        "claude-code",
        "--open-web-dashboard",
        "{{#if (eq project.environment 'development')}}true{{else}}false{{/if}}"
      ],
      "tags": ["filesystem", "search", "semantic"]
    }
  }
}

Use case: Auto-launch the web dashboard in development for visual exploration, but disable it in CI/CD or production.

Example 3: Language Backend Selection

Use JetBrains language backend for specific projects:

json

{
  "mcpTemplates": {
    "jetbrains-serena": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena",
        "serena",
        "start-mcp-server",
        "--project",
        "{{project.path}}",
        "--context",
        "{{#if (eq transport.client.name 'cursor')}}ide{{else}}claude-code{{/if}}",
        "--language-backend",
        "{{#if project.custom.useJetBrains}}JetBrains{{/if}}"
      ],
      "tags": ["filesystem", "search", "semantic"]
    }
  }
}

Use case: Advanced projects can opt into JetBrains plugin-based language support via custom metadata.

Example 4: HTTP Transport with Custom Port

Run Serena over HTTP for remote access:

json

{
  "mcpTemplates": {
    "http-serena": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena",
        "serena",
        "start-mcp-server",
        "--project",
        "{{project.path}}",
        "--context",
        "claude-code",
        "--transport",
        "streamable-http",
        "--port",
        "{{#if project.custom.serenaPort}}{{project.custom.serenaPort}}{{else}}24283{{/if}}"
      ],
      "tags": ["filesystem", "search", "semantic"]
    }
  }
}

Use case: Remote access scenarios or when you need to expose Serena over HTTP instead of STDIO.

Best Practices

2. Choose the Correct Context

Match context to your client type:

Client Type	Recommended Context
Claude Code CLI	`claude-code`
Cursor, VSCode	`ide`
Codex CLI	`codex`
Custom agent	Create custom context

3. Tag Appropriately

Always include semantic analysis tags:

json

{
  "tags": ["filesystem", "search", "semantic"]
}

This enables proper server filtering with presets.

5. Environment-Based Disabling

6. Project Setup

For optimal performance, initialize Serena in your project:

bash

cd /path/to/your/project
serena project create --index

This creates .serena/project.yml and builds the initial symbol index.

7. Client-Aware Selection

Serena-Specific Features

Symbol-Level Operations

Serena provides powerful semantic tools:

find_symbol: Locate classes, functions, methods by name or pattern
find_referencing_symbols: Find all references to a symbol
get_symbols_overview: Get high-level code structure
replace_symbol_body: Modify symbol definitions
insert_after_symbol: Add code after symbols
insert_before_symbol: Add code before symbols
rename_symbol: Rename symbols across the codebase

Language Support

Serena supports 30+ languages via LSP, including:

Web: TypeScript, JavaScript, HTML, CSS
Backend: Python, Java, Go, Rust, C/C++, C#
Mobile: Swift, Kotlin, Dart
Data: SQL, R, Julia
Config: YAML, JSON, TOML

Project Indexing

For large projects, build an index for faster symbol lookup:

bash

# One-time indexing
serena project index

# Or during project creation
serena project create --index

Web Dashboard

Serena auto-launches a web dashboard at http://localhost:24282/dashboard for visual code exploration.

Disable the dashboard:

json

{
  "args": ["--open-web-dashboard", "false"]
}

Context System

Different contexts provide different tool sets:

claude-code: Full semantic toolkit for CLI agents
ide: Minimal tools to avoid IDE duplication
codex: Codex-compatible tool configuration

Create custom contexts via ~/.serena/serena_config.yml.

Troubleshooting

Context Parameter Not Working

Symptom: Wrong tools available or context parameter ignored

Solutions:

Verify context name is valid: claude-code, ide, codex, or custom
Check for typos in template conditional logic
Ensure custom contexts are defined in ~/.serena/serena_config.yml

Performance Issues with Large Projects

Symptoms: Slow symbol lookup, high memory usage

Solutions:

Build symbol index: serena project index
Use .serenignore to exclude unnecessary directories (node_modules, build, etc.)
Consider using --language-backend JetBrains for better performance on large codebases

Dashboard Not Opening

Symptom: Web dashboard doesn't launch automatically

Solutions:

Check if port 24282 is already in use
Manually open: http://localhost:24282/dashboard
Disable auto-launch: --open-web-dashboard false

Serena Integration ​

Overview ​

Why Use Serena with 1MCP Templates? ​

Key Capabilities ​

Quick Start ​

Basic Static Configuration ​

Template-Based Configuration (Recommended) ​

Template Variables ​

Project Path Injection ​

Instance Sharing ​

Context-Aware Configuration ​

Available Context Types ​

Client-Aware Context Selection ​

Multi-Client Context Mapping ​

Project-Level Configuration ​

Using .1mcprc for Custom Context ​

Serena's Own Configuration ​

Complete Examples ​

Example 1: Multi-Environment Setup ​

Example 2: Dashboard Control ​

Example 3: Language Backend Selection ​

Example 4: HTTP Transport with Custom Port ​

Best Practices ​

2. Choose the Correct Context ​

3. Tag Appropriately ​

5. Environment-Based Disabling ​

6. Project Setup ​

7. Client-Aware Selection ​

Serena-Specific Features ​

Symbol-Level Operations ​

Language Support ​

Project Indexing ​

Web Dashboard ​

Context System ​

Troubleshooting ​

Context Parameter Not Working ​

Performance Issues with Large Projects ​

Dashboard Not Opening ​

See Also ​

Serena Integration

Overview

Why Use Serena with 1MCP Templates?

Key Capabilities

Quick Start

Basic Static Configuration

Template-Based Configuration (Recommended)

Template Variables

Project Path Injection

Instance Sharing

Context-Aware Configuration

Available Context Types

Client-Aware Context Selection

Multi-Client Context Mapping

Project-Level Configuration

Using .1mcprc for Custom Context

Serena's Own Configuration

Complete Examples

Example 1: Multi-Environment Setup

Example 2: Dashboard Control

Example 3: Language Backend Selection

Example 4: HTTP Transport with Custom Port

Best Practices

2. Choose the Correct Context

3. Tag Appropriately

5. Environment-Based Disabling

6. Project Setup

7. Client-Aware Selection

Serena-Specific Features

Symbol-Level Operations

Language Support

Project Indexing

Web Dashboard

Context System

Troubleshooting

Context Parameter Not Working

Performance Issues with Large Projects

Dashboard Not Opening

See Also